diff options
Diffstat (limited to 'release_docs/INSTALL_CMake.txt')
| -rw-r--r-- | release_docs/INSTALL_CMake.txt | 98 |
1 files changed, 96 insertions, 2 deletions
diff --git a/release_docs/INSTALL_CMake.txt b/release_docs/INSTALL_CMake.txt index b9d8338..ac04855 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 ************************************************************************ @@ -209,10 +210,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.15."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.15."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.15."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.15."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.15."X" @@ -1042,6 +1043,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 ======================================================================== |