Add support for CMakePresets and fix example download (#2819)

2 files changed, 106 insertions, 4 deletions

diff --git a/release_docs/INSTALL_CMake.txt b/release_docs/INSTALL_CMake.txt
index db2d375..361e3e6 100644
--- a/release_docs/INSTALL_CMake.txt
+++ b/release_docs/INSTALL_CMake.txt
@@ -14,6 +14,7 @@ Section VI:   CMake option defaults for HDF5
 Section VII:  User Defined Options for HDF5 Libraries with CMake
 Section VIII: User Defined Compile Flags for HDF5 Libraries with CMake
 Section IX:   Considerations for cross-compiling
+Section X:    Using CMakePresets.json for compiling
 
 ************************************************************************
 
@@ -210,10 +211,10 @@ Notes: This short set of instructions is written for users who want to
       5. Configure the C library, tools and tests with one of the following commands:
 
          On Windows 32 bit
-           cmake -G "Visual Studio 12 2013" -DCMAKE_BUILD_TYPE:STRING=Release -DBUILD_SHARED_LIBS:BOOL=OFF -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON ..\hdf5-1.12."X"
+           cmake -G "Visual Studio 16 2019" -A Win32 -DCMAKE_BUILD_TYPE:STRING=Release -DBUILD_SHARED_LIBS:BOOL=OFF -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON ..\hdf5-1.12."X"
 
          On Windows 64 bit
-           cmake -G "Visual Studio 12 2013 Win64" -DCMAKE_BUILD_TYPE:STRING=Release -DBUILD_SHARED_LIBS:BOOL=OFF -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON ..\hdf5-1.12."X"
+           cmake -G "Visual Studio 16 2019 Win64" -A x64 -DCMAKE_BUILD_TYPE:STRING=Release -DBUILD_SHARED_LIBS:BOOL=OFF -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON ..\hdf5-1.12."X"
 
          On Linux and Mac
            cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE:STRING=Release -DBUILD_SHARED_LIBS:BOOL=OFF -DBUILD_TESTING:BOOL=ON -DHDF5_BUILD_TOOLS:BOOL=ON ../hdf5-1.12."X"
@@ -616,7 +617,6 @@ These five steps are described in detail below.
                 set (ZFP_TGZ_NAME "zfp.tar.gz" CACHE STRING "Use ZFP from compressed file" FORCE)
                 set (ZFP_PACKAGE_NAME "zfp" CACHE STRING "Name of ZFP package" FORCE)
 
-
    2. Configure the cache settings
 
       2.1  Visual CMake users, click the Configure button. If this is the first time you are
@@ -639,7 +639,7 @@ These five steps are described in detail below.
 
       2.2  Preferred command line example on Windows in c:\MyHDFstuff\hdf5\build directory:
 
-               cmake -C ../config/cmake/cacheinit.cmake -G "Visual Studio 12 2013" \
+               cmake -C ../config/cmake/cacheinit.cmake -G "Visual Studio 16 2019" "-Ax64"\
                -DHDF5_ENABLE_SZIP_SUPPORT:BOOL=OFF -DHDF5_ENABLE_Z_LIB_SUPPORT:BOOL=OFF \
                -DCMAKE_BUILD_TYPE:STRING=Release ..
 
@@ -1020,6 +1020,99 @@ The HDF5 CMake variables;
     HDF5_USE_PREGEN: set this to true
     HDF5_USE_PREGEN_DIR: set this path to the preset H5Tinit.c file
 
+
+========================================================================
+X:    Using CMakePresets.json for compiling
+========================================================================
+
+One problem that CMake users often face is sharing settings with other people for common
+ways to configure a project. This may be done to support CI builds, or for users who
+frequently use the same build. CMake supports two main files, CMakePresets.json and CMakeUserPresets.json,
+that allow users to specify common configure options and share them with others. CMake also supports
+files included with the include field.
+
+CMakePresets.json and CMakeUserPresets.json live in the project's root directory. They
+both have exactly the same format, and both are optional (though at least one must be
+present if --preset is specified). CMakePresets.json is meant to specify project-wide build
+details, while CMakeUserPresets.json is meant for developers to specify their own local build details.
+
+See CMake documentation for details: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html
+
+HDF-provided CMakePresets.json
+-------------------------------
+The CMakePresets.json provided by HDF requires CMake version 3.25, which supports package
+and workflow presets, and ninja build system. The top-level configuration group is intended to be
+a standard set of options to produce a package of shared and staic libraries and tools. Other configurations
+used for inheriting settings are in the included json file in "config/cmake-presets/hidden-presets.json".
+
+Available configurations presets can be displayed by executing:
+    cmake -S <path-to-source> --list-presets
+
+Using individual command presets (where <compiler-type> is  GNUC or MSVC or Clang):
+    change directory to the hdf5 source folder
+    cmake --presets=ci-StdShar-<compiler-type>
+    cmake --build --presets=ci-StdShar-<compiler-type>
+    ctest --presets=ci-StdShar-<compiler-type>
+    cpack --presets=ci-StdShar-<compiler-type>
+
+
+Using the workflow preset to configure, build, test and package the standard configuration is:
+    change directory to the hdf5 source folder
+    execute "cmake --workflow --presets=ci-StdShar-<compiler-type> --fresh"
+          where <compiler-type> is  GNUC or MSVC or Clang
+
+Creating your own configurations
+--------------------------------
+The quickest way is to copy CMakePresets.json to CMakeUserPresets.json and
+edit CMakeUserPresets.json configuration names from ci-* to my-*. Change the
+"configurePresets" section "inherits" field only for those that you have alternate
+options. Then change the "configurePreset" field entries in the "buildPresets",
+"testPresets", "packagePresets" sections to match your my-StdShar-<compiler-type>.
+And finally the names settings in the "workflowPresets" steps will also need the ci-* to my-* change.
+
+For instance, to change the support files to use a local directory, edit CMakeUserPresets.json:
+......
+    {
+      "name": "my-base-tgz",
+      "hidden": true,
+      "inherits": "ci-base",
+      "cacheVariables": {
+        "HDF5_ALLOW_EXTERNAL_SUPPORT": {"type": "STRING", "value": "TGZ"},
+        "TGZPATH": {"type": "STRING", "value": "${sourceParentDir}/temp"}
+      }
+    },
+    {
+      "name": "my-StdCompression",
+      "hidden": true,
+      "inherits": "my-base-tgz",
+      "cacheVariables": {
+......
+   {
+      "name": "my-StdShar",
+      "hidden": true,
+      "inherits": "my-StdCompression",
+      "cacheVariables": {
+......
+    {
+      "name": "my-StdShar-GNUC",
+      "description": "GNUC Standard Config for x64 (Release)",
+      "inherits": [
+        "ci-x64-Release-GNUC",
+        "ci-CPP",
+        "ci-Fortran",
+        "ci-Java",
+        "my-StdShar",
+        "my-StdExamples"
+      ]
+    }
+......
+
+
+Then you can change or add options for your specific case.
+
+
+
+
 ========================================================================
 For further assistance, send email to help@hdfgroup.org
 ========================================================================
diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt
index 5856d81..1c14ab7 100644
--- a/release_docs/RELEASE.txt
+++ b/release_docs/RELEASE.txt
@@ -47,6 +47,15 @@ New Features
 
     Configuration:
     -------------
+    - Added support for CMake presets file.
+
+      CMake supports two main files, CMakePresets.json and CMakeUserPresets.json,
+      that allow users to specify common configure options and share them with others.
+      HDF added a CMakePresets.json file of a typical configuration and support
+      file, config/cmake-presets/hidden-presets.json. 
+      Also added a section to INSTALL_CMake.txt with very basic explanation of the
+      process to use CMakePresets.
+
     - Enabled instrumentation of the library by default in CMake for parallel
       debug builds