mirrors/hdf5
2
0
Fork 0
mirror of https://github.com/HDFGroup/hdf5.git synced 2026-09-25 04:09:44 +03:00
Code Issues Packages Projects Releases Wiki Activity

Improvements to CMake logic for handling filters (#6287)

Browse Source 
* Re-write zlib/szip CMake logic for clarity

* Update external libaec, zlib-ng and zlib builds to not use patching process

* Add FindZLIBNG module to locate zlib-ng on system

* Rework HDF5 filter plugins support
This commit is contained in:
jhendersonHDF
2026-03-16 13:46:48 -05:00
committed by GitHub
parent 950f47492f
commit 5a11a79fc4
54 changed files with 1878 additions and 5979 deletions
Download Patch File Download Diff File Expand all files Collapse all files
release_docs/BuildSystemNotes.md
-1
View File
@@ -14,7 +14,6 @@ A comprehensive analysis of the HDF5 CMake-only build system and CI/CD infrastru
#### Main Configuration Files
- `CMakeLists.txt` - Root build configuration
- `CMakeBuildOptions.cmake` - Centralized build option definitions
- `CMakeFilters.cmake` - Compression filter support (zlib, szip, libaec)
- `CMakeTests.cmake` - Testing infrastructure configuration
- `CMakeInstallation.cmake` - Installation and packaging setup
- `CMakeVOL.cmake` - Virtual Object Layer connector support
release_docs/CHANGELOG.md
+30
View File
@@ -15,6 +15,7 @@ For releases prior to version 2.0.0, please see the release.txt file and for mor
## 📖 Contents
* [Executive Summary](CHANGELOG.md#execsummary)
* [Breaking Changes](CHANGELOG.md#%EF%B8%8F-breaking-changes)
* [Deprecations](CHANGELOG.md#-deprecations)
* [New Features & Improvements](CHANGELOG.md#-new-features--improvements)
* [Bug Fixes](CHANGELOG.md#-bug-fixes)
* [Support for new platforms and languages](CHANGELOG.md#-support-for-new-platforms-and-languages)
@@ -40,6 +41,7 @@ For releases prior to version 2.0.0, please see the release.txt file and for mor
## Enhanced Features:
- Made several improvements to the CMake logic for handling filter libraries
## Java Enhancements:
@@ -50,11 +52,39 @@ We would like to thank the many HDF5 community members who contributed to this r
# ⚠️ Breaking Changes
# 🪦 Deprecations
- The CMake variable `ZLIB_GIT_BRANCH` has been deprecated in favor of `ZLIB_GIT_TAG`
- The CMake variable `ZLIBNG_GIT_BRANCH` has been deprecated in favor of `ZLIBNG_GIT_TAG`
- The CMake variable `LIBAEC_GIT_BRANCH` has been deprecated in favor of `LIBAEC_GIT_TAG`
- The CMake variable `PLUGIN_GIT_BRANCH` has been deprecated in favor of `HDF5_FILTER_PLUGINS_GIT_TAG`
- The CMake variable `PLUGIN_GIT_URL` has been deprecated in favor of `HDF5_FILTER_PLUGINS_GIT_URL`
- The CMake variable `PLUGIN_TGZ_NAME` has been deprecated in favor of `HDF5_FILTER_PLUGINS_TGZ_NAME`
- The CMake variable `PLUGIN_TGZ_ORIGPATH` has been deprecated in favor of `HDF5_FILTER_PLUGINS_TGZ_ORIGPATH`
- The CMake variable `PLUGIN_PACKAGE_NAME` has been deprecated in favor of `HDF5_FILTER_PLUGINS_PACKAGE_NAME`
# 🚀 New Features & Improvements
## Configuration
### Updated external building of zlib, zlib-ng and libaec to not use a patching process
When building these libraries from external sources while building HDF5, the library previously used a patching process to adapt the libraries to its own build process. The sources for these libraries are no longer patched and build directly from the sources of the latest upstream releases (currently, zlib 1.3.2, zlib-ng 2.3.3 and libaec 1.1.6). This also fixed an issue with the build of zlib-ng failing due to updates that were made since the last version that HDF5 was patching the sources for.
Fixes GitHub issue #6204
### Fixed an issue where CMake-built installations of zlib libraries couldn't be located on a system
An incorrect package name was being supplied to CMake's find_package() function when attempting to locate zlib libraries on the system in Config mode. The package name has been corrected and CMake-built zlib libraries can now be located.
### Fixed an issue where static zlib libraries couldn't be found on the system
The value of the HDF5 CMake variable `HDF5_USE_ZLIB_STATIC` was previously used incorrectly when locating zlib libraries on the system with CMake's find_package() function, causing it to have no effect. This has been fixed and static zlib libraries can now be located.
### Added a CMake module to locate zlib-ng for zlib support
A new `FindZLIBNG.cmake` CMake module has been added. This module is intended to locate zlib-ng on the system for zlib support in HDF5 when zlib-ng was built with Autotools instead of CMake. When zlib-ng support is enabled in HDF5 with the `HDF5_ENABLE_ZLIB_SUPPORT` and `HDF5_USE_ZLIB_NG` options, this module will first check for an existing CMake-built zlib-ng and use that if it's available. Otherwise, the module will heuristically search for zlib-ng on the system. If necessary, the module can be hinted toward a particular zlib-ng installation by setting the CMake variable `ZLIBNG_ROOT` to point to a directory.
### Added a CMake module to locate libaec for SZIP support
A new `Findlibaec.cmake` CMake module has been added. This module is intended to locate libaec on the system for SZIP support in HDF5 when libaec was built with Autotools instead of CMake. When SZIP support is enabled in HDF5 with the `HDF5_ENABLE_SZIP_SUPPORT` option, this module will first check for an existing CMake-built libaec and use that if it's available. Otherwise, the module will heuristically search for libaec on the system. If necessary, the module can be hinted toward a particular libaec installation by setting the CMake variable `libaec_ROOT` to point to a directory. If it is known that a CMake-built libaec installation exists on the system in a non-standard location, the CMake variable `libaec_DIR` can instead be set to a directory containing a `libaec-config.cmake` file to cause the module to prefer that libaec installation.
release_docs/INSTALL_CMake.md
+14 -215
View File
@@ -367,109 +367,9 @@ Go through these steps:
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):
2. If you plan to use Zlib/Zlib-ng, Szip (aka libaec) and/or HDF5 filter plugins, refer to the instructions in [INSTALL_Filters.md](./INSTALL_Filters.md).
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"`<br/>
`ZLIB_GIT_URL:STRING="https://some_location/zlib"` or `ZLIBNG_GIT_URL:STRING="https://some_location/zlibng"`<br/>
`ZLIB_GIT_BRANCH="some_branch"` or `ZLIBNG_GIT_BRANCH="some_branch"`<br/>
`SZIP_GIT_URL:STRING="https://some_location/szip"`<br/>
`SZIP_GIT_BRANCH="some_branch"`<br/>
`LIBAEC_GIT_URL:STRING="https://some_location/libaec"`<br/>
`LIBAEC_GIT_BRANCH="some_branch"`<br/>
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"`<br/>
`ZLIB_TGZ_NAME:STRING="zlib_src.ext"` or `ZLIBNG_TGZ_NAME:STRING="zlibng_src.ext"`<br/>
`LIBAEC_TGZ_NAME:STRING="libaec_src.ext"`<br/>
`TGZPATH:STRING="some_location"`<br/>
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"`<br/>
`LIBAEC_TGZ_ORIGPATH:STRING="some_location"`<br/>
`ZLIB_TGZ_NAME:STRING="zlib_src.ext"` or `ZLIBNG_TGZ_NAME:STRING="zlibng_src.ext"`<br/>
`ZLIB_TGZ_ORIGPATH:STRING="some_location"` or Z`LIBNG_TGZ_ORIGPATH:STRING="some_location"`<br/>
`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:
3. 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.
@@ -480,9 +380,9 @@ Go through these steps:
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.
4. 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:
5. 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:
```cmd
cmake -C ../config/cmake/cacheinit.cmake ^
@@ -493,7 +393,7 @@ Go through these steps:
..
```
7. CMake uses a toolchain of utilities to compile, link libraries,
6. 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
@@ -592,7 +492,9 @@ turn specific options on or off for testing using the following command line wit
cmake -C <sourcepath>/config/cmake/cacheinit.cmake -G "<generator>" [-D<options>] <sourcepath>
Where `<generator>` is (examples):
Where `cacheinit.cmake` is a file used to populate an initial CMake cache with some common option settings,
`<generator>` is (examples):
* MinGW Makefiles
* NMake Makefiles
* Unix Makefiles
@@ -602,74 +504,10 @@ Where `<generator>` is (examples):
* 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>
and `<options>` are any CMake options to be added to the configuration:
* `<HDF5OPTION>:BOOL=[ON | OFF]`
`cacheinit.cmake` highlights are:
```cmake
# 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.
@@ -715,48 +553,9 @@ 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:
```cmake
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:
```cmake
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.
External libraries (zlib, szip and plugins) can be configured to allow
building the libraries by downloading from a GIT repository or by using
a compressed file. See the instructions in [INSTALL_Filters.md](./INSTALL_Filters.md) to do this.
### Step 4: Test HDF5
@@ -1123,8 +922,8 @@ If `BUILD_TESTING` is true:
| `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"` |
| `HDF5_FILTER_PLUGINS_TGZ_ORIGPATH` | Use PLUGIN from original location | `"https://github.com/HDFGroup/hdf5_plugins/releases/download/snapshot"` |
| `HDF5_FILTER_PLUGINS_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**)<br/>`"/usr/local/hdf5/lib/plugin"` |
release_docs/INSTALL_Filters.md
+173
View File
@@ -0,0 +1,173 @@
# Build HDF5 with support for data filters
This file provides instructions for building HDF5 with support for various data filters, including zlib and libaec.
---
## Table of Contents
* [CMake options](#cmake-options)
* [Zlib options](#zlib-options)
* [Zlib-ng options](#zlib-ng-options)
* [Libaec (szip) options](#libaec-szip-options)
* [HDF5 filter plugins options](#hdf5-filter-plugins-options)
* [Using system-installed libraries](#using-system-installed-libraries)
* [Using libraries built with CMake FetchContent](#using-libraries-built-with-cmake-fetchcontent)
* [CMake options for `HDF5_ALLOW_EXTERNAL_SUPPORT=GIT`](#cmake-options-for-hdf5_allow_external_supportgit)
* [CMake options for `HDF5_ALLOW_EXTERNAL_SUPPORT=TGZ`](#cmake-options-for-hdf5_allow_external_supporttgz)
* [Troubleshooting](#troubleshooting)
---
## CMake options
<a name="cmake_options"></a>
HDF5 currently has built-in support for zlib, zlib-ng and libaec (szip), as well as support for a collection of dynamically-loaded filter libraries from the [HDF5 filter plugins](https://github.com/HDFGroup/hdf5_plugins) repository, which are controlled by the following CMake options:
- `HDF5_ENABLE_ZLIB_SUPPORT` (`ON`/`OFF` Default: `OFF`) - Enable zlib support
- `HDF5_ENABLE_SZIP_SUPPORT` (`ON`/`OFF` Default: `OFF`) - Enable libaec (szip) support
- `HDF5_USE_ZLIB_NG` (`ON`/`OFF` Default: `OFF`) - Enable zlib-ng support
- `HDF5_ENABLE_PLUGIN_SUPPORT` (`ON`/`OFF` Default: `OFF`) - Enable support for plugins from the HDF5 filter plugins repository
- `HDF5_ALLOW_EXTERNAL_SUPPORT` (`NO`/`GIT`/`TGZ` Default: `NO`) - Specify whether support for libraries from external sources should be enabled (see [Using libraries built with CMake FetchContent](#fetchcontent_building))
- `TGZPATH` (`<path>` Default: top level of HDF5 source directory) - When `HDF5_ALLOW_EXTERNAL_SUPPORT` is `TGZ` and a filter's `_USE_LOCALCONTENT` variable is `ON` (see below), specifies the directory to look in for a library's source code compressed file.
By default, setting `HDF5_ENABLE_ZLIB_SUPPORT` to `ON` will enable support for zlib. Setting the additional option `HDF5_USE_ZLIB_NG` to `ON` will cause HDF5 to instead use zlib-ng in place of zlib.
Additional CMake options for controlling how specific filters are found/used include the following:
### Zlib options
- `HDF5_USE_ZLIB_STATIC` (`ON`/`OFF` Default: `OFF`) - Prefer locating and using static zlib libraries (if available) instead of shared libraries
- `ZLIB_USE_EXTERNAL` (`ON`/`OFF` Default: `OFF`) - If `ON` and `HDF5_ALLOW_EXTERNAL_SUPPORT` is `GIT` or `TGZ`, instructs HDF5 to build zlib from an external source and use that while building HDF5 itself. If `ON` and `HDF5_ALLOW_EXTERNAL_SUPPORT` is `NO`, causes a configuration error.
- `ZLIB_USE_LOCALCONTENT` (`ON`/`OFF` Default: `OFF`) - If `ON`, `HDF5_ALLOW_EXTERNAL_SUPPORT` is `TGZ` and `ZLIB_USE_EXTERNAL` is `ON`, instructs HDF5 to build zlib from a compressed source file on the filesystem, which is pointed to by the path formed from combining `TGZPATH` and `ZLIB_TGZ_NAME`, and use that while building HDF5 itself. If `ON` and `HDF5_ALLOW_EXTERNAL_SUPPORT` is `NO` or `GIT`, causes a configuration error.
- `HDF5_MODULE_MODE_ZLIB` (`ON`/`OFF` Default: `ON`) - If `ON`, locates zlib using CMake's [find_package()](https://cmake.org/cmake/help/latest/command/find_package.html) Module mode search, otherwise uses a Config mode search. In most cases this option should be left to the default value, but may need to be modified for specific zlib installations.
- `ZLIB_GIT_URL` (`<url>` Default: [zlib](https://github.com/madler/zlib.git)) - Specifies the git URL to retrieve zlib from when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `GIT` and `ZLIB_USE_EXTERNAL` is `ON` (e.g., when building zlib with CMake's FetchContent)
- `ZLIB_GIT_TAG` / `ZLIB_GIT_BRANCH` (`<git tag>` Default: `v<zlib_version>`) - Specifies the git tag, commit hash or branch name to use for retrieving zlib when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `GIT` and `ZLIB_USE_EXTERNAL` is `ON` (e.g., when building zlib with CMake's FetchContent). `ZLIB_GIT_BRANCH` is deprecated in favor of `ZLIB_GIT_TAG`.
- `ZLIB_TGZ_NAME` (`<filename>` Default: `zlib-<zlib_version>.tar.gz`) - Specifies the base filename of a compressed file containing the zlib source code which will be used when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `TGZ` and `ZLIB_USE_EXTERNAL` is `ON`. Combined with either `TGZPATH` or `ZLIB_TGZ_ORIGPATH`, depending on the value of `ZLIB_USE_LOCALCONTENT`, to form a full path to the compressed file.
- `ZLIB_TGZ_ORIGPATH` (`<url>` Default: `https://github.com/madler/zlib/releases/download/v<zlib_version>`) - Specifies the URL to retrieve a compressed file containing the zlib source code from when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `TGZ`, `ZLIB_USE_EXTERNAL` is `ON` and `ZLIB_USE_LOCALCONTENT` is `OFF`. Combined with `ZLIB_TGZ_NAME` to form a full URL for the download.
- `ZLIB_PACKAGE_NAME` (`<string>` Default: `zlib`) - The package name to use when locating zlib libraries with CMake's [find_package()](https://cmake.org/cmake/help/latest/command/find_package.html). Usually should be left to the default value but may need to be modified in rare circumstances.
### Zlib-ng options
> [!NOTE]
> The `HDF5_USE_ZLIB_STATIC`, `ZLIB_USE_EXTERNAL` and `ZLIB_USE_LOCALCONTENT` options also apply to zlib-ng when `HDF5_USE_ZLIB_NG` is set to `ON`.
- `ZLIBNG_GIT_URL` (`<url>` Default: [zlib-ng](https://github.com/zlib-ng/zlib-ng.git)) - Specifies the git URL to retrieve zlib-ng from when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `GIT`, `ZLIB_USE_EXTERNAL` is `ON` and `HDF5_USE_ZLIB_NG` is `ON` (e.g., when building zlib-ng with CMake's FetchContent)
- `ZLIBNG_GIT_TAG` / `ZLIBNG_GIT_BRANCH` (`<git tag>` Default: `<zlibng_version>`) - Specifies the git tag, commit hash or branch name to use for retrieving zlib-ng when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `GIT`, `ZLIB_USE_EXTERNAL` is `ON` and `HDF5_USE_ZLIB_NG` is `ON` (e.g., when building zlib-ng with CMake's FetchContent). `ZLIBNG_GIT_BRANCH` is deprecated in favor of `ZLIBNG_GIT_TAG`.
- `ZLIBNG_TGZ_NAME` (`<filename>` Default: `<zlibng_version>.tar.gz`) - Specifies the base filename of a compressed file containing the zlib-ng source code which will be used when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `TGZ`, `ZLIB_USE_EXTERNAL` is `ON` and `HDF5_USE_ZLIB_NG` is `ON`. Combined with either `TGZPATH` or `ZLIBNG_TGZ_ORIGPATH`, depending on the value of `ZLIB_USE_LOCALCONTENT`, to form a full path to the compressed file.
- `ZLIBNG_TGZ_ORIGPATH` (`<url>` Default: `https://github.com/zlib-ng/zlib-ng/archive/refs/tags`) - Specifies the URL to retrieve a compressed file containing the zlib-ng source code from when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `TGZ`, `ZLIB_USE_EXTERNAL` is `ON`, `ZLIB_USE_LOCALCONTENT` is `OFF` and `HDF5_USE_ZLIB_NG` is `ON`. Combined with `ZLIBNG_TGZ_NAME` to form a full URL for the download.
- `ZLIBNG_PACKAGE_NAME` (`<string>` Default: `ZLIBNG`) - The package name to use when locating zlib-ng libraries with CMake's [find_package()](https://cmake.org/cmake/help/latest/command/find_package.html). Usually should be left to the default value but may need to be modified in rare circumstances.
### Libaec (szip) options
- `HDF5_USE_LIBAEC_STATIC` (`ON`/`OFF` Default: `OFF`) - Prefer locating and using static libaec libraries (if available) instead of shared libraries
- `SZIP_USE_EXTERNAL` (`ON`/`OFF` Default: `OFF`) - If `ON` and `HDF5_ALLOW_EXTERNAL_SUPPORT` is `GIT` or `TGZ`, instructs HDF5 to build libaec from an external source and use that while building HDF5 itself. If `ON` and `HDF5_ALLOW_EXTERNAL_SUPPORT` is `NO`, causes a configuration error.
- `LIBAEC_USE_LOCALCONTENT` (`ON`/`OFF` Default: `OFF`) - If `ON`, `HDF5_ALLOW_EXTERNAL_SUPPORT` is `TGZ` and `SZIP_USE_EXTERNAL` is `ON`, instructs HDF5 to build libaec from a compressed source file on the filesystem, which is pointed to by the path formed from combining `TGZPATH` and `LIBAEC_TGZ_NAME`, and use that while building HDF5 itself. If `ON` and `HDF5_ALLOW_EXTERNAL_SUPPORT` is `NO` or `GIT`, causes a configuration error.
- `LIBAEC_GIT_URL` (`<url>` Default: [libaec](https://github.com/MathisRosenhauer/libaec.git)) - Specifies the git URL to retrieve libaec from when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `GIT` and `SZIP_USE_EXTERNAL` is `ON` (e.g., when building libaec with CMake's FetchContent)
- `LIBAEC_GIT_TAG` / `LIBAEC_GIT_BRANCH` (`<git tag>` Default: `v<libaec_version>`) - Specifies the git tag, commit hash or branch name to use for retrieving libaec when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `GIT` and `SZIP_USE_EXTERNAL` is `ON` (e.g., when building libaec with CMake's FetchContent). `LIBAEC_GIT_BRANCH` is deprecated in favor of `LIBAEC_GIT_TAG`.
- `LIBAEC_TGZ_NAME` (`<filename>` Default: `libaec-<libaec_version>.tar.gz`) - Specifies the base filename of a compressed file containing the libaec source code which will be used when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `TGZ` and `SZIP_USE_EXTERNAL` is `ON`. Combined with either `TGZPATH` or `LIBAEC_TGZ_ORIGPATH`, depending on the value of `LIBAEC_USE_LOCALCONTENT`, to form a full path to the compressed file.
- `LIBAEC_TGZ_ORIGPATH` (`<url>` Default: `https://github.com/MathisRosenhauer/libaec/releases/download/v<libaec_version>`) - Specifies the URL to retrieve a compressed file containing the libaec source code from when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `TGZ`, `SZIP_USE_EXTERNAL` is `ON` and `LIBAEC_USE_LOCALCONTENT` is `OFF`. Combined with `LIBAEC_TGZ_NAME` to form a full URL for the download.
- `LIBAEC_PACKAGE_NAME` (`<string>` Default: `libaec`) - The package name to use when locating libaec libraries with CMake's [find_package()](https://cmake.org/cmake/help/latest/command/find_package.html). Usually should be left to the default value but may need to be modified in rare circumstances.
- `HDF5_ENABLE_SZIP_ENCODING` (`ON`/`OFF` Default: `ON`) - Specifies whether encoding should be enabled for the HDF5 szip filter. Deprecated option that is no longer used.
### HDF5 filter plugins options
- `PLUGIN_USE_EXTERNAL` (`ON`/`OFF` Default: `OFF`) - If `ON` and `HDF5_ALLOW_EXTERNAL_SUPPORT` is `GIT` or `TGZ`, instructs HDF5 to build several dynamically-loaded data filter plugins from the [hdf5_plugins](https://github.com/HDFGroup/hdf5_plugins) repository while building HDF5 itself. If `ON` and `HDF5_ALLOW_EXTERNAL_SUPPORT` is `NO`, causes a configuration error.
- `PLUGIN_USE_LOCALCONTENT` (`ON`/`OFF` Default: `OFF`) - If `ON`, `HDF5_ALLOW_EXTERNAL_SUPPORT` is `TGZ` and `PLUGIN_USE_EXTERNAL` is `ON`, instructs HDF5 to build several dynamically-loaded data filter plugins from a compressed source file on the filesystem, which is pointed to by the path formed from combining `TGZPATH` and `HDF5_FILTER_PLUGINS_TGZ_NAME` / `PLUGIN_TGZ_NAME`, and use that while building HDF5 itself. If `ON` and `HDF5_ALLOW_EXTERNAL_SUPPORT` is `NO` or `GIT`, causes a configuration error.
- `HDF5_FILTER_PLUGINS_GIT_URL` / `PLUGIN_GIT_URL` (`<url>` Default: [hdf5_plugins](https://github.com/HDFGroup/hdf5_plugins.git)) - Specifies the git URL to retrieve HDF5 filter plugins from when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `GIT` and `PLUGIN_USE_EXTERNAL` is `ON` (e.g., when building HDF5 filter plugins with CMake's FetchContent). `PLUGIN_GIT_URL` is deprecated in favor of `HDF5_FILTER_PLUGINS_GIT_URL`.
- `HDF5_FILTER_PLUGINS_GIT_TAG` / `PLUGIN_GIT_BRANCH` (`<git tag>` Default: `master`) - Specifies the git tag, commit hash or branch name to use for retrieving HDF5 filter plugins when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `GIT` and `PLUGIN_USE_EXTERNAL` is `ON` (e.g., when building HDF5 filter plugins with CMake's FetchContent). `PLUGIN_GIT_BRANCH` is deprecated in favor of `HDF5_FILTER_PLUGINS_GIT_TAG`.
- `HDF5_FILTER_PLUGINS_TGZ_NAME` / `PLUGIN_TGZ_NAME` (`<filename>` Default: `hdf5_plugins-master.tar.gz`) - Specifies the base filename of a compressed file containing the HDF5 filter plugins source code which will be used when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `TGZ` and `PLUGIN_USE_EXTERNAL` is `ON`. Combined with either `TGZPATH` or `HDF5_FILTER_PLUGINS_TGZ_ORIGPATH` / `PLUGIN_TGZ_ORIGPATH`, depending on the value of `PLUGIN_USE_LOCALCONTENT`, to form a full path to the compressed file. `PLUGIN_TGZ_NAME` is deprecated in favor of `HDF5_FILTER_PLUGINS_TGZ_NAME`.
- `HDF5_FILTER_PLUGINS_TGZ_ORIGPATH` / `PLUGIN_TGZ_ORIGPATH` (`<url>` Default: `https://github.com/HDFGroup/hdf5_plugins/releases/download/snapshot`) - Specifies the URL to retrieve a compressed file containing the HDF5 filter plugins source code from when `HDF5_ALLOW_EXTERNAL_SUPPORT` is `TGZ`, `PLUGIN_USE_EXTERNAL` is `ON` and `PLUGIN_USE_LOCALCONTENT` is `OFF`. Combined with `HDF5_FILTER_PLUGINS_TGZ_NAME` / `PLUGIN_TGZ_NAME` to form a full URL for the download. `PLUGIN_TGZ_ORIGPATH` is deprecated in favor of `HDF5_FILTER_PLUGINS_TGZ_ORIGPATH`.
- `HDF5_FILTER_PLUGINS_PACKAGE_NAME` / `PLUGIN_PACKAGE_NAME` (`<string>` Default: `h5pl`) - The package name to use when locating HDF5 filter plugins libraries with CMake's [find_package()](https://cmake.org/cmake/help/latest/command/find_package.html). Usually should be left to the default value but may need to be modified in rare circumstances. `PLUGIN_PACKAGE_NAME` is deprecated in favor of `HDF5_FILTER_PLUGINS_PACKAGE_NAME`.
## Using system-installed libraries
To build HDF5 with data filter support using libraries that are installed on the system, setting the relevant `HDF5_ENABLE_XXX_SUPPORT` [CMake options](#cmake_options) to `ON` should be enough in most cases. However, CMake can be instructed to look for specific libraries if desired or if the needed libraries are installed to directories that aren't in CMake's default search paths:
- For zlib, set the CMake variable `ZLIB_ROOT` to the top level directory of a zlib installation
- For zlib-ng, set the CMake variable `ZLIBNG_ROOT` to the top level directory of a zlib installation
- For libaec (szip), set the CMake variable `SZIP_ROOT` or `libaec_ROOT` to the top level directory of a libaec installation
<b>Example:</b> Configure HDF5 with zlib and libaec support from system libraries
```bash
cmake -DHDF5_ENABLE_ZLIB_SUPPORT=ON -DHDF5_ENABLE_SZIP_SUPPORT=ON <hdf5_source_dir>
```
<b>Example:</b> Configure HDF5 with zlib installed to a non-system directory
```bash
cmake -DHDF5_ENABLE_ZLIB_SUPPORT=ON -DZLIB_ROOT=/path/to/my/zlib/installation <hdf5_source_dir>
```
<b>Example:</b> Configure HDF5 with zlib-ng static libraries installed to a non-system directory
```bash
cmake -DHDF5_ENABLE_ZLIB_SUPPORT=ON -DHDF5_USE_ZLIB_NG=ON -DHDF5_USE_ZLIB_STATIC=ON -DZLIBNG_ROOT=/path/to/my/zlib-ng/installation <hdf5_source_dir>
```
## Using libraries built with CMake FetchContent
<a name="fetchcontent_building"></a>
> [!WARNING]
> HDF5 does not currently namespace libraries that are built using CMake's FetchContent functionality. Use caution when installing HDF5 to a system directory if any libraries are built this way, as there is risk of overwriting pre-existing libraries on the system. For this reason, it is recommended to install filter libraries on the system and allow HDF5 to find them at build time instead. This method is only provided as a convenience for building HDF5 binaries and for testing of HDF5.
When building HDF5, one may choose to build the libraries for data filters alongside HDF5 by using CMake's FetchContent functionality.
This will either download the source code for libraries or use compressed source code files from the filesystem and add the source code to the HDF5 build and installation processes. To set up this method, several CMake variables need to be set when configuring HDF5. First, the CMake variable `HDF5_ALLOW_EXTERNAL_SUPPORT` must be set to the value `GIT` or `TGZ`. The value `GIT` will instruct the HDF5 build process to retrieve the source code for libraries from git URLs, whereas the value `TGZ` will instruct the build process to retrieve the source code for libraries from compressed files from either a web URL or a path on the filesystem.
Next, external support for the desired data filters needs to be configured into HDF5. This simply involves setting the relevant `HDF5_ENABLE_XXX_SUPPORT` and `XXX_USE_EXTERNAL` [CMake options](#cmake_options) to `ON`.
Finally, any CMake options for how the source code should be retrieved and built must be set. The default values set for most of these options can be found in [CacheURLs.cmake](../config/CacheURLs.cmake) and can be changed by setting values for the CMake variables listed there. Note that the `HDF5_USE_XXX_STATIC` options affect which type of library, shared or static, is built when building external libraries.
> [!TIP]
> CMake options for a library can generally be passed through when building them with FetchContent by defining those options when configuring HDF5 (e.g., add `-DZLIB_BUILD_TESTING=OFF` to the list of HDF5 configuration options), but be aware that HDF5 may override the values for some of these variables.
### CMake options for `HDF5_ALLOW_EXTERNAL_SUPPORT=GIT`
When the `HDF5_ALLOW_EXTERNAL_SUPPORT` CMake option is specified as `GIT`, all filter libraries will be downloaded from git URLs using a specified git tag, commit hash or branch name. For example, using the default values for libaec will cause CMake to download the libaec source from `https://github.com/MathisRosenhauer/libaec.git` (`LIBAEC_GIT_URL`) using the git tag `v1.1.6` (`LIBAEC_GIT_TAG` as of the time of writing). Each filter's `_GIT_URL` and `_GIT_TAG` CMake variables may have values specified for them to change where the source code is downloaded from.
<b>Example:</b> Configure HDF5 with zlib-ng from system libraries and libaec (szip) from the default git repository
```bash
cmake -DHDF5_ALLOW_EXTERNAL_SUPPORT=GIT -DHDF5_ENABLE_ZLIB_SUPPORT=ON -DHDF5_USE_ZLIB_NG=ON -DHDF5_ENABLE_SZIP_SUPPORT=ON -DSZIP_USE_EXTERNAL=ON <hdf5_source_dir>
```
<b>Example:</b> Configure HDF5 with zlib-ng, libaec and the HDF5 filter plugins from the default git repositories
```bash
cmake -DHDF5_ALLOW_EXTERNAL_SUPPORT=GIT -DHDF5_ENABLE_ZLIB_SUPPORT=ON -DHDF5_USE_ZLIB_NG=ON -DZLIB_USE_EXTERNAL=ON -DHDF5_ENABLE_SZIP_SUPPORT=ON -DSZIP_USE_EXTERNAL=ON -DHDF5_ENABLE_PLUGIN_SUPPORT=ON -DPLUGIN_USE_EXTERNAL=ON <hdf5_source_dir>
```
<b>Example:</b> Configure HDF5 with libaec from a custom git repository
```bash
cmake -DHDF5_ALLOW_EXTERNAL_SUPPORT=GIT -DHDF5_ENABLE_SZIP_SUPPORT=ON -DSZIP_USE_EXTERNAL=ON -DLIBAEC_GIT_URL="https://github.com/user/libaec.git" -DLIBAEC_GIT_TAG="my_libaec_tag" <hdf5_source_dir>
```
### CMake options for `HDF5_ALLOW_EXTERNAL_SUPPORT=TGZ`
When the `HDF5_ALLOW_EXTERNAL_SUPPORT` CMake option is specified as `TGZ`, the way in which filter libraries are retrieved depends on the value for that filter's `_USE_LOCALCONTENT` CMake option. For each filter that has its `_USE_LOCALCONTENT` variable set to `OFF`, CMake will download a compressed file with the relevant library's source code from a URL formed by combining the filter's `_TGZ_ORIGPATH` and `_TGZ_NAME` CMake variables. For example, the default values of `LIBAEC_TGZ_ORIGPATH` and `LIBAEC_TGZ_NAME` are `https://github.com/MathisRosenhauer/libaec/releases/download/v<libaec_version>` and `libaec-<libaec_version>.tar.gz`, respectively. As of the time of writing, the current default version of libaec is 1.1.6, resulting in a URL of https://github.com/MathisRosenhauer/libaec/releases/download/v1.1.6/libaec-1.1.6.tar.gz. CMake will download this file, uncompress it and use the contents as source code when building the library alongside HDF5. Each filter's `_TGZ_ORIGPATH` and `_TGZ_NAME` CMake variables may have values specified for them to change where the file is downloaded from.
For each filter that has its `_USE_LOCALCONTENT` variable set to `ON`, CMake will search the directory specified by `TGZPATH` for the compressed file with that filter's library source code according to the default names, which can be changed by setting a filter's `_TGZ_NAME` variable. For example, to locate compressed files with zlib and libaec libraries with the names `zlib.tar.gz` and `libaec.tar.gz` in the directory `/home/user/filters`, specify the following CMake options when configuring HDF5:
- `-DTGZPATH="/home/user/filters"`
- `-DZLIB_TGZ_NAME="zlib.tar.gz"`
- `-DLIBAEC_TGZ_NAME="libaec.tar.gz"`
CMake will combine `TGZPATH` with each of `ZLIB_TGZ_NAME` and `LIBAEC_TGZ_NAME` to form full paths to each file.
<b>Example:</b> Configure HDF5 with zlib-ng and libaec from downloaded tar.gz files with the default names
```bash
cmake -DHDF5_ALLOW_EXTERNAL_SUPPORT=TGZ -DHDF5_ENABLE_ZLIB_SUPPORT=ON -DHDF5_USE_ZLIB_NG=ON -DZLIB_USE_EXTERNAL=ON -DHDF5_ENABLE_SZIP_SUPPORT=ON -DSZIP_USE_EXTERNAL=ON <hdf5_source_dir>
```
<b>Example:</b> Configure HDF5 with zlib-ng and libaec from tar.gz files on the system with custom names
```bash
cmake -DHDF5_ALLOW_EXTERNAL_SUPPORT=TGZ -DTGZPATH="/path/to/files" -DHDF5_ENABLE_ZLIB_SUPPORT=ON -DHDF5_USE_ZLIB_NG=ON -DZLIB_USE_EXTERNAL=ON -DZLIB_USE_LOCALCONTENT=ON -DZLIBNG_TGZ_NAME="zlib-ng-2.3.3.tar.gz" -DHDF5_ENABLE_SZIP_SUPPORT=ON -DSZIP_USE_EXTERNAL=ON -DLIBAEC_USE_LOCALCONTENT=ON -DLIBAEC_TGZ_NAME="libaec-1.1.6.tar.gz" <hdf5_source_dir>
```
## Troubleshooting
If the HDF5 build process does not properly locate libraries for a data filter on the system, debugging of the process can be enabled when configuring HDF5 by passing the option `-DCMAKE_FIND_DEBUG_MODE=ON`. This option is intended for advanced users, but will give information about what paths on the system are or are not being searched.
release_docs/MAINTAINERS.md
+26
View File
@@ -0,0 +1,26 @@
# HDF5 Library maintainer's notes
This document is a catch-all file with general notes for HDF5 library maintainers.
---
## Table of Contents
* [Maintaining external libraries built with CMake FetchContent](#maintaining-external-libraries-built-with-cmake-fetchcontent)
* [Updating libraries to new versions](#updating-libraries-to-new-versions)
---
## Maintaining external libraries built with CMake FetchContent
### Updating libraries to new versions
When performing a new release of HDF5, external libraries that can be fetched and built with CMake's FetchContent should be checked and updated as necessary. For filter libraries, this involves the following steps:
- For each library being updated:
- Modify [CacheURLs.cmake](../config/CacheURLs.cmake) and [CMakePresets.json](../CMakePresets.json) to set the new version of the library, git/tgz URL, git tag, etc.
- Check the library's source code for any change in CMake logic, including target names and export namespaces, installed configuration files, etc. and make adjustments to the CMake logic in HDF5 that sets up to build that library
- If the library's source is being patched by HDF5, check for any adjustments that need to be made to the file(s) being patched and create a new version, ideally with the source version in the file name, to be used by the patching process
- Check the library's source code for any new CMake options or settings that should be enabled/disabled or set near the relevant `FetchContent_MakeAvailable()` call in the CMake logic that will fetch and configure the source
- Check the library's source code for any new CMake options or settings that should be marked as advanced with `mark_as_advanced()` _after_ the relevant `FetchContent_MakeAvailable()` call in order to hide them from CMake GUI programs and prevent a clutter of build options
- Test building and installing HDF5 with the updated libraries being obtained with FetchContent to check for any new issues