Document CMake options in a central location

.github/workflows/netcdf.yml

@@ -53,7 +53,8 @@ jobs:
             -G Ninja \
             --log-level=VERBOSE \
             -DCMAKE_BUILD_TYPE=Release \
-            -DHDF5_ONLY_SHARED_LIBS:BOOL=ON \
+            -DBUILD_SHARED_LIBS=ON \
+            -DBUILD_STATIC_LIBS=OFF \
             -DHDF5_ENABLE_PARALLEL:BOOL=OFF \
             -DHDF5_BUILD_CPP_LIB:BOOL=OFF \
             -DHDF5_BUILD_FORTRAN:BOOL=OFF \

CMakeBuildOptions.cmake

@@ -42,9 +42,16 @@ mark_as_advanced (HDF5_MINGW_STATIC_GCC_LIBS)
 
 option (HDF5_ENABLE_TRACE "Enable API tracing capability" OFF)
 mark_as_advanced (HDF5_ENABLE_TRACE)
+if (HDF5_ENABLE_TRACE)
+  message (DEPRECATION "HDF5_ENABLE_TRACE has been deprecated and may be removed in a future release of HDF5")
+endif ()
 
-option (HDF5_ENABLE_EMBEDDED_LIBINFO "Embed library info into executables" ON)
+option (HDF5_ENABLE_EMBEDDED_LIBINFO "Embed library info into executables" OFF)
 mark_as_advanced (HDF5_ENABLE_EMBEDDED_LIBINFO)
+if (HDF5_ENABLE_EMBEDDED_LIBINFO)
+  message (DEPRECATION "HDF5_ENABLE_EMBEDDED_LIBINFO has been deprecated and may be removed in a future release of HDF5")
+endif ()
+
 
 option (HDF5_ENABLE_HDFS "Enable HDFS" OFF)
 

CMakeLists.txt

@@ -727,7 +727,7 @@ endif ()
 #-----------------------------------------------------------------------------
 if (${HDF_CFG_NAME} MATCHES "Debug" OR ${HDF_CFG_NAME} MATCHES "Developer")
   # Enable instrumenting of the library's internal operations
-  cmake_dependent_option (HDF5_ENABLE_INSTRUMENT "Instrument The library" OFF HDF5_ENABLE_TRACE OFF)
+  cmake_dependent_option (HDF5_ENABLE_INSTRUMENT "Instrument the library" OFF HDF5_ENABLE_PARALLEL OFF)
 
   # Instrumenting is enabled by default for parallel debug builds
   if (HDF5_ENABLE_PARALLEL)

config/cmake/scripts/HDF5options.cmake

@@ -31,8 +31,6 @@
 #############################################################################################
 ####      Only build static libraries       ####
 #set (ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DBUILD_SHARED_LIBS:BOOL=OFF")
-####      Only build shared libraries       ####
-#set (ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_ONLY_SHARED_LIBS:BOOL=OFF")
 ####      Add PIC option on linux/mac       ####
 #set (ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DCMAKE_ANSI_CFLAGS:STRING=-fPIC")
 

release_docs/BuildSystemNotes.md

@@ -25,7 +25,6 @@ A comprehensive analysis of the HDF5 CMake-only build system and CI/CD infrastru
 **Library Types:**
 - `BUILD_STATIC_LIBS=ON` - Static library builds
 - `BUILD_SHARED_LIBS=ON` - Shared library builds
-- `HDF5_ONLY_SHARED_LIBS=OFF` - Force shared-only builds
 - `HDF5_BUILD_STATIC_TOOLS=OFF` - Static vs shared tools
 
 **Language Bindings:**

release_docs/INSTALL_CMake.md

@@ -676,38 +676,7 @@ the following options must be disabled:
 <a id="section-vii"></a>
 ## 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` |
+See [INSTALL_CMake_options](./INSTALL_CMake_options.md).
 
 #### Java Implementation Selection (as of HDF5 2.0)
 
@@ -783,179 +752,6 @@ The HDF5 Java examples are available as a separate Maven artifact: `org.hdfgroup
 - 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,<br/>`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` |
-| `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"` |
-
-> **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`.
-
 ---
 
 <a id="section-viii"></a>