mirror of
https://github.com/HDFGroup/hdf5.git
synced 2026-09-25 04:09:44 +03:00
Improve install and documentation (#5438)
This commit is contained in:
Allen Byrne
@@ -0,0 +1,234 @@
|
||||
#
|
||||
# Copyright by The HDF Group.
|
||||
# All rights reserved.
|
||||
#
|
||||
# This file is part of HDF5. The full HDF5 copyright notice, including
|
||||
# terms governing use, modification, and redistribution, is contained in
|
||||
# the LICENSE file, which can be found at the root of the source code
|
||||
# distribution tree, or in https://www.hdfgroup.org/licenses.
|
||||
# If you do not have access to either file, you may request a copy from
|
||||
# help@hdfgroup.org.
|
||||
#
|
||||
#############################################################################################
|
||||
# This file contains macros for finding HDF5 and/or building HDF5 using FetchContent
|
||||
#############################################################################################
|
||||
#
|
||||
# This macro is used to build HDF5 as a subdirectory using FetchContent to get the source code
|
||||
# and build it. The HDF5 options should be set after the FetchContent_Declare command and before
|
||||
# the add_subdirectory command..
|
||||
macro (EXTERNAL_HDF5_LIBRARY compress_type)
|
||||
set (HDF5_VERSION "2.0.0")
|
||||
set (HDF5_VERSION_MAJOR "2.0")
|
||||
set (HDF5LIB_TGZ_NAME "hdf5.tar.gz" CACHE STRING "Use HDF5LIB from compressed file" FORCE)
|
||||
set (HDF5LIB_TGZ_ORIGPATH "https://github.com/HDFGroup/hdf5/releases/download/snapshot" CACHE STRING "Use HDF5LIB from original location" FORCE)
|
||||
set (HDF5LIB_USE_LOCALCONTENT ON CACHE BOOL "Use local file for HDF5LIB FetchContent" FORCE)
|
||||
set (HDF5LIB_GIT_URL "https://github.com/HDFGroup/hdf5.git" CACHE STRING "Use HDF5LIB from GitHub repository" FORCE)
|
||||
set (HDF5LIB_GIT_BRANCH "develop" CACHE STRING "" FORCE)
|
||||
if (NOT HDF5LIB_USE_LOCALCONTENT)
|
||||
set (HDF5LIB_URL ${TGZ_DIR}/${HDF5LIB_TGZ_NAME}) #TGZ_DIR is set in the top level CMakeLists.txt
|
||||
else ()
|
||||
set (HDF5LIB_URL ${HDF5LIB_TGZ_ORIGPATH}/${HDF5LIB_TGZ_NAME})
|
||||
endif ()
|
||||
message (VERBOSE "Library HDF5LIB file is ${HDF5LIB_URL}")
|
||||
if (${compress_type} MATCHES "GIT")
|
||||
FetchContent_Declare (HDF5LIB
|
||||
GIT_REPOSITORY ${HDF5LIB_GIT_URL}
|
||||
GIT_TAG ${HDF5LIB_GIT_BRANCH}
|
||||
)
|
||||
elseif (${compress_type} MATCHES "TGZ")
|
||||
message (VERBOSE "Library HDF5LIB file ${HDF5LIB_URL}")
|
||||
FetchContent_Declare (HDF5LIB
|
||||
URL ${HDF5LIB_URL}
|
||||
URL_HASH ""
|
||||
)
|
||||
endif ()
|
||||
FetchContent_GetProperties(HDF5LIB)
|
||||
if(NOT hdf5lib_POPULATED)
|
||||
FetchContent_Populate(HDF5LIB)
|
||||
|
||||
# Adjust variables for building HDF5
|
||||
set (BUILD_SHARED_LIBS OFF CACHE BOOL "Build Shared Libraries" FORCE)
|
||||
set (HDF5_BUILD_CPP_LIB OFF CACHE BOOL "Build C++ support" FORCE)
|
||||
set (HDF5_BUILD_FORTRAN OFF CACHE BOOL "Build FORTRAN support" FORCE)
|
||||
set (HDF5_BUILD_JAVA OFF CACHE BOOL "Build JAVA support" FORCE)
|
||||
set (BUILD_TESTING OFF CACHE BOOL "Build JHDF5 Unit Testing" FORCE)
|
||||
set (HDF5_BUILD_EXAMPLES OFF CACHE BOOL "Build JHDF5 Library Examples" FORCE)
|
||||
set (HDF5_BUILD_HL_LIB OFF CACHE BOOL "Build JHDF5 HIGH Level HDF5 Library" FORCE)
|
||||
set (HDF5_ENABLE_Z_LIB_SUPPORT OFF CACHE BOOL "Enable Zlib Filters" FORCE)
|
||||
set (HDF5_ENABLE_SZIP_SUPPORT OFF CACHE BOOL "Use SZip Filter" FORCE)
|
||||
|
||||
add_subdirectory(${hdf5lib_SOURCE_DIR} ${hdf5lib_BINARY_DIR})
|
||||
endif()
|
||||
|
||||
add_library(${HDF_PACKAGE_NAMESPACE}hdf5lib-static ALIAS hdf5-static)
|
||||
set (H5LIB_STATIC_LIBRARY "${HDF_PACKAGE_NAMESPACE}hdf5lib-static")
|
||||
set (H5LIB_LIBRARIES ${H5LIB_STATIC_LIBRARY})
|
||||
set (H5LIB_TOOLS ${hdf5lib_BINARY_DIR}/bin})
|
||||
|
||||
set (H5LIB_INCLUDE_DIR_GEN "${hdf5lib_BINARY_DIR}/src")
|
||||
set (H5LIB_INCLUDE_DIR "${hdf5lib_SOURCE_DIR}/src")
|
||||
set (H5LIB_FOUND 1)
|
||||
set (H5LIB_INCLUDE_DIRS ${H5LIB_INCLUDE_DIR_GEN} ${H5LIB_INCLUDE_DIR})
|
||||
message (STATUS "HDF5-${HDF5_VERSION} found: INC=${H5LIB_INCLUDE_DIRS} TOOLS=${H5LIB_TOOLS}")
|
||||
endmacro ()
|
||||
|
||||
# this macro is used to find HDF5 in the parent project. It can be used
|
||||
# to build HDF5 as a subdirectory using FetchContent or to find HDF5 using
|
||||
# the find_package command. The macro should be called in the parent project
|
||||
macro (HDF5_SUPPORT EXTNAME) #EXTNAME is the extension name used in the parent project
|
||||
# H5_RESOURCES_DIR is set in the top level CMakeLists.txt
|
||||
set (CMAKE_MODULE_PATH ${H5${EXTNAME}_RESOURCES_DIR} ${CMAKE_MODULE_PATH})
|
||||
option (USE_SHARED_LIBS "Use Shared Libraries" ON)
|
||||
|
||||
if (HDF_FETCH_HDF5)
|
||||
include (FetchContent)
|
||||
EXTERNAL_HDF5_LIBRARY(GIT)
|
||||
set (H5${EXTNAME}_HDF5_INCLUDE_DIRS ${H5LIB_INCLUDE_DIRS})
|
||||
set (H5${EXTNAME}_HDF5_HAVE_H5PUBCONF_H 1)
|
||||
set (H5${EXTNAME}_HDF5_HAVE_HDF5 1)
|
||||
set (H5${EXTNAME}_HDF5_HEADER "h5pubconf.h")
|
||||
set (H5${EXTNAME}_HDF5_LINK_LIBS ${H5${EXTNAME}_HDF5_LINK_LIBS} ${H5LIB_LIBRARIES})
|
||||
if (NOT TARGET h5dump)
|
||||
add_executable (h5dump IMPORTED)
|
||||
endif()
|
||||
set (H5${EXTNAME}_HDF5_DUMP_EXECUTABLE $<TARGET_FILE:h5dump>)
|
||||
else ()
|
||||
if (NOT H5${EXTNAME}_HDF5_HEADER)
|
||||
if (USE_SHARED_LIBS)
|
||||
set (FIND_HDF_COMPONENTS C shared)
|
||||
else ()
|
||||
set (FIND_HDF_COMPONENTS C static)
|
||||
set (HDF_BUILD_JAVA OFF CACHE BOOL "Build Java support" FORCE)
|
||||
message (STATUS "Using static HDF5 - disable build of Java examples")
|
||||
endif ()
|
||||
if (HDF_BUILD_FORTRAN)
|
||||
set (FIND_HDF_COMPONENTS ${FIND_HDF_COMPONENTS} Fortran)
|
||||
endif ()
|
||||
if (HDF_BUILD_JAVA)
|
||||
set (FIND_HDF_COMPONENTS ${FIND_HDF_COMPONENTS} Java)
|
||||
set (HDF5_Java_FOUND 1) #default setting for 1.10.1 and earlier
|
||||
endif ()
|
||||
message (STATUS "HDF5 find comps: ${FIND_HDF_COMPONENTS}")
|
||||
set (SEARCH_PACKAGE_NAME ${HDF5_PACKAGE_NAME})
|
||||
|
||||
find_package (HDF5 NAMES ${SEARCH_PACKAGE_NAME} COMPONENTS ${FIND_HDF_COMPONENTS})
|
||||
message (STATUS "HDF5 C libs:${HDF5_FOUND} static:${HDF5_static_C_FOUND} and shared:${HDF5_shared_C_FOUND}")
|
||||
message (STATUS "HDF5 Fortran libs: static:${HDF5_static_Fortran_FOUND} and shared:${HDF5_shared_Fortran_FOUND}")
|
||||
message (STATUS "HDF5 Java libs: ${HDF5_Java_FOUND}")
|
||||
if (HDF5_FOUND)
|
||||
if (NOT HDF5_static_C_FOUND AND NOT HDF5_shared_C_FOUND)
|
||||
#find library from non-dual-binary package
|
||||
set (FIND_HDF_COMPONENTS C)
|
||||
if (HDF_BUILD_FORTRAN)
|
||||
set (FIND_HDF_COMPONENTS ${FIND_HDF_COMPONENTS} Fortran)
|
||||
endif ()
|
||||
if (HDF_BUILD_JAVA)
|
||||
set (FIND_HDF_COMPONENTS ${FIND_HDF_COMPONENTS} Java)
|
||||
endif ()
|
||||
message (STATUS "HDF5 find comps: ${FIND_HDF_COMPONENTS}")
|
||||
|
||||
find_package (HDF5 NAMES ${SEARCH_PACKAGE_NAME} COMPONENTS ${FIND_HDF_COMPONENTS})
|
||||
message (STATUS "HDF5 libs:${HDF5_FOUND} C:${HDF5_C_FOUND} Fortran:${HDF5_Fortran_FOUND} Java:${HDF5_Java_FOUND}")
|
||||
set (H5${EXTNAME}_HDF5_LINK_LIBS ${H5${EXTNAME}_HDF5_LINK_LIBS} ${HDF5_LIBRARIES})
|
||||
if (HDF5_BUILD_SHARED_LIBS)
|
||||
add_definitions (-DH5_BUILT_AS_DYNAMIC_LIB)
|
||||
else ()
|
||||
add_definitions (-DH5_BUILT_AS_STATIC_LIB)
|
||||
endif ()
|
||||
if (USE_SHARED_LIBS AND WIN32)
|
||||
set_property (TARGET ${HDF5_NAMESPACE}h5dump PROPERTY IMPORTED_LOCATION "${HDF5_TOOLS_DIR}/h5dumpdll")
|
||||
else ()
|
||||
set_property (TARGET ${HDF5_NAMESPACE}h5dump PROPERTY IMPORTED_LOCATION "${HDF5_TOOLS_DIR}/h5dump")
|
||||
endif ()
|
||||
if (HDF_BUILD_JAVA)
|
||||
set (CMAKE_JAVA_INCLUDE_PATH "${CMAKE_JAVA_INCLUDE_PATH};${HDF5_JAVA_INCLUDE_DIRS}")
|
||||
message (STATUS "HDF5 jars:${HDF5_JAVA_INCLUDE_DIRS}")
|
||||
endif ()
|
||||
set (H5${EXTNAME}_HDF5_DUMP_EXECUTABLE $<TARGET_FILE:${HDF5_NAMESPACE}h5dump>)
|
||||
else ()
|
||||
if (USE_SHARED_LIBS AND HDF5_shared_C_FOUND)
|
||||
set (H5${EXTNAME}_HDF5_LINK_LIBS ${H5${EXTNAME}_HDF5_LINK_LIBS} ${HDF5_C_SHARED_LIBRARY})
|
||||
set (HDF5_LIBRARY_PATH ${PACKAGE_PREFIX_DIR}/lib)
|
||||
else ()
|
||||
set (H5${EXTNAME}_HDF5_LINK_LIBS ${H5${EXTNAME}_HDF5_LINK_LIBS} ${HDF5_C_STATIC_LIBRARY})
|
||||
endif ()
|
||||
if (HDF5_VERSION VERSION_LESS "1.14.4" AND NOT HDF5_shared_C_FOUND)
|
||||
if (NOT TARGET ${HDF5_NAMESPACE}h5dump-shared)
|
||||
add_executable (${HDF5_NAMESPACE}h5dump-shared IMPORTED)
|
||||
endif ()
|
||||
set (H5${EXTNAME}_HDF5_DUMP_EXECUTABLE $<TARGET_FILE:${HDF5_NAMESPACE}h5dump-shared>)
|
||||
else ()
|
||||
if (NOT TARGET ${HDF5_NAMESPACE}h5dump)
|
||||
add_executable (${HDF5_NAMESPACE}h5dump IMPORTED)
|
||||
endif()
|
||||
set (H5${EXTNAME}_HDF5_DUMP_EXECUTABLE $<TARGET_FILE:${HDF5_NAMESPACE}h5dump>)
|
||||
endif()
|
||||
|
||||
if (NOT HDF5_static_Fortran_FOUND AND NOT HDF5_shared_Fortran_FOUND)
|
||||
set (HDF_BUILD_FORTRAN OFF CACHE BOOL "Build FORTRAN support" FORCE)
|
||||
message (STATUS "HDF5 Fortran libs not found - disable build of Fortran examples")
|
||||
else ()
|
||||
if (HDF_BUILD_FORTRAN AND ${HDF5_BUILD_FORTRAN})
|
||||
if (BUILD_SHARED_LIBS AND HDF5_shared_Fortran_FOUND)
|
||||
set (H5${EXTNAME}_HDF5_LINK_LIBS ${H5${EXTNAME}_HDF5_LINK_LIBS} ${HDF5_FORTRAN_SHARED_LIBRARY})
|
||||
elseif (HDF5_static_Fortran_FOUND)
|
||||
set (H5${EXTNAME}_HDF5_LINK_LIBS ${H5${EXTNAME}_HDF5_LINK_LIBS} ${HDF5_FORTRAN_STATIC_LIBRARY})
|
||||
else ()
|
||||
set (HDF_BUILD_FORTRAN OFF CACHE BOOL "Build FORTRAN support" FORCE)
|
||||
message (STATUS "HDF5 Fortran libs not found - disable build of Fortran examples")
|
||||
endif ()
|
||||
endif ()
|
||||
endif ()
|
||||
if (HDF_BUILD_JAVA AND HDF5_Java_FOUND)
|
||||
if (${HDF5_BUILD_JAVA})
|
||||
set (CMAKE_JAVA_INCLUDE_PATH "${CMAKE_JAVA_INCLUDE_PATH};${HDF5_JAVA_INCLUDE_DIRS}")
|
||||
set (H5${EXTNAME}_JAVA_LIBRARY ${HDF5_JAVA_LIBRARY})
|
||||
set (H5${EXTNAME}_JAVA_LIBRARIES ${HDF5_JAVA_LIBRARY})
|
||||
message (STATUS "HDF5 lib:${H5${EXTNAME}_JAVA_LIBRARY} jars:${HDF5_JAVA_INCLUDE_DIRS}}")
|
||||
else ()
|
||||
set (HDF_BUILD_JAVA OFF CACHE BOOL "Build Java support" FORCE)
|
||||
message (STATUS "HDF5 Java libs not found - disable build of Java examples")
|
||||
endif ()
|
||||
else ()
|
||||
set (HDF_BUILD_JAVA OFF CACHE BOOL "Build Java support" FORCE)
|
||||
endif ()
|
||||
endif ()
|
||||
else ()
|
||||
find_package (HDF5) # Legacy find
|
||||
#Legacy find_package does not set HDF5_TOOLS_DIR, so we set it here
|
||||
set (HDF5_TOOLS_DIR ${HDF5_LIBRARY_DIRS}/../bin)
|
||||
#Legacy find_package does not set HDF5_BUILD_SHARED_LIBS, so we set it here
|
||||
if (USE_SHARED_LIBS AND EXISTS "${HDF5_LIBRARY_DIRS}/libhdf5.so")
|
||||
set (HDF5_BUILD_SHARED_LIBS 1)
|
||||
else ()
|
||||
set (HDF5_BUILD_SHARED_LIBS 0)
|
||||
endif ()
|
||||
set (H5${EXTNAME}_HDF5_LINK_LIBS ${H5${EXTNAME}_HDF5_LINK_LIBS} ${HDF5_LIBRARIES})
|
||||
add_executable (${HDF5_NAMESPACE}h5dump IMPORTED)
|
||||
set_property (TARGET ${HDF5_NAMESPACE}h5dump PROPERTY IMPORTED_LOCATION "${HDF5_TOOLS_DIR}/h5dump")
|
||||
set (H5${EXTNAME}_HDF5_DUMP_EXECUTABLE $<TARGET_FILE:${HDF5_NAMESPACE}h5dump>)
|
||||
endif ()
|
||||
|
||||
set (HDF5_PACKAGE_NAME ${SEARCH_PACKAGE_NAME})
|
||||
|
||||
if (HDF5_FOUND)
|
||||
set (H5${EXTNAME}_HDF5_INCLUDE_DIRS ${HDF5_INCLUDE_DIR})
|
||||
set (H5${EXTNAME}_HDF5_HAVE_H5PUBCONF_H 1)
|
||||
set (H5${EXTNAME}_HDF5_HAVE_HDF5 1)
|
||||
set (H5${EXTNAME}_HDF5_HEADER "h5pubconf.h")
|
||||
message (STATUS "HDF5-${HDF5_VERSION_STRING} found: INC=${HDF5_INCLUDE_DIR} TOOLS=${HDF5_TOOLS_DIR}")
|
||||
else ()
|
||||
message (FATAL_ERROR " HDF5 is Required for HDF5 Examples")
|
||||
endif ()
|
||||
else ()
|
||||
# This project is being called from within another and HDF5 is already configured
|
||||
set (H5${EXTNAME}_HDF5_HAVE_H5PUBCONF_H 1)
|
||||
set (H5${EXTNAME}_HDF5_HAVE_HDF5 1)
|
||||
message (STATUS "HDF5-${HDF5_VERSION_STRING} used")
|
||||
endif ()
|
||||
if (HDF_BUILD_FORTRAN)
|
||||
list (APPEND H5${EXTNAME}_HDF5_INCLUDE_DIRS ${HDF5_INCLUDE_DIR_FORTRAN})
|
||||
endif ()
|
||||
endif ()
|
||||
message (STATUS "HDF5 link libs: ${H5${EXTNAME}_HDF5_LINK_LIBS} Includes: ${H5${EXTNAME}_HDF5_INCLUDE_DIRS}")
|
||||
endmacro ()
|
||||
@@ -41,6 +41,11 @@ if (DOXYGEN_FOUND)
|
||||
DESTINATION ${HDF5_INSTALL_DOC_DIR}
|
||||
COMPONENT hdfdocuments
|
||||
)
|
||||
install (
|
||||
FILES ${HDF5_BINARY_DIR}/hdf5.tag
|
||||
DESTINATION ${HDF5_INSTALL_DOC_DIR}
|
||||
COMPONENT hdfdocuments
|
||||
)
|
||||
|
||||
if (NOT TARGET doxygen)
|
||||
add_custom_target (doxygen)
|
||||
|
||||
+40
-28
@@ -20,8 +20,8 @@ CONTENTS
|
||||
2.2 Szip (optional)
|
||||
2.3 MPI and MPI-IO
|
||||
3. HDF5 Source Code and Precompiled Binaries
|
||||
4. Build and Install HDF5 on Unix and Mac OSX Platforms with Autotools
|
||||
5. Build and Install HDF5 Libraries and Tools with CMake
|
||||
4. Build and Install HDF5 Libraries and Tools with CMake
|
||||
5. Quick Start Presets
|
||||
|
||||
*****************************************************************************
|
||||
|
||||
@@ -30,35 +30,20 @@ CONTENTS
|
||||
https://github.com/HDFGroup/hdf5.
|
||||
|
||||
2. Third-party Software Requirements
|
||||
To see what compression was configured into a built HDF5 library,
|
||||
check the "I/O filters (external):" line in the libhdf5.settings file.
|
||||
Also, the hdf5-config.cmake file contains the list of configuration
|
||||
options used to build the library.
|
||||
|
||||
2.1. zlib
|
||||
The HDF5 library includes a predefined compression filter that
|
||||
uses the "deflate" method for chunked datasets. If zlib-1.1.2 or
|
||||
later is found, HDF5 will use it. Otherwise, HDF5's predefined
|
||||
compression method will be disabled; the compression
|
||||
filter will succeed but the data will not be compressed.
|
||||
uses the "deflate" method for chunked datasets.
|
||||
|
||||
2.2. Szip (optional)
|
||||
2.2. szip
|
||||
The HDF5 library includes a predefined compression filter that
|
||||
uses the extended-Rice lossless compression algorithm for chunked
|
||||
datasets.
|
||||
|
||||
Szip source code includes build instructions.
|
||||
|
||||
The HDF Group does not distribute separate Szip precompiled libraries,
|
||||
but the HDF5 pre-built binaries provided on The HDF Group download page
|
||||
include the Szip library with the encoder enabled. These can be found
|
||||
here:
|
||||
|
||||
https://support.hdfgroup.org/downloads/index.html
|
||||
|
||||
Please notice that if HDF5 configure cannot find a valid Szip library,
|
||||
configure will not fail; in this case, the compression filter will
|
||||
not be available to the applications.
|
||||
|
||||
To check if Szip compression was successfully configured in,
|
||||
check the "I/O filters (external):" line in the configure output,
|
||||
summary section, printed to the standard output.
|
||||
|
||||
2.3. MPI and MPI-IO
|
||||
The parallel version of the library is built upon the foundation
|
||||
provided by MPI and MPI-IO. If these libraries are not available
|
||||
@@ -70,8 +55,35 @@ CONTENTS
|
||||
|
||||
https://github.com/HDFGroup/hdf5/releases
|
||||
|
||||
4. Build and Install HDF5 on Unix and Mac OSX Platforms with Autotools
|
||||
see the release_docs/INSTALL_Autotools.txt file.
|
||||
|
||||
5. Build and Install HDF5 Libraries and Tools with CMake
|
||||
4. Build and Install HDF5 Libraries and Tools with CMake
|
||||
see the release_docs/INSTALL_CMake.txt file.
|
||||
|
||||
5. Quick Start Presets
|
||||
You want to build HDF5 with CMake, but there are so many options to consider.
|
||||
|
||||
5.1. Solution
|
||||
CMake introduced presets in version 3.19. HDF Group provides a file in the source,
|
||||
CMakePresets.json, requiring CMake 3.24 or higher, that will build HDF5 with the
|
||||
options for building a typical shared library with the common languages for a
|
||||
platform. The features include building the tools, examples, plugins, and the
|
||||
shared and static libraries.
|
||||
|
||||
5.2. Discussion
|
||||
The CMakePresets.json file is located in the root directory of the HDF5 source.
|
||||
It is from here you will execute the cmake command to build HDF5. The following
|
||||
example shows how to build HDF5 with the CMakePresets.json file:
|
||||
- change directory to the hdf5 source folder
|
||||
- execute "cmake --workflow --preset ci-StdShar-<compiler-type> --fresh"
|
||||
where "<compiler-type>" is GNUC, MSVC, Clang
|
||||
|
||||
The above example will create a "build" folder in the source parent directory, which
|
||||
will contain the results of the build, including installation package files.
|
||||
|
||||
5.3. Customization
|
||||
See the HDF5 documentation for more on presets, especially the presets section in:
|
||||
- release_docs/INSTALL_CMake.txt file
|
||||
|
||||
5.4. See Also
|
||||
See CMake documentation for details on presets:
|
||||
- https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html
|
||||
|
||||
|
||||
@@ -33,6 +33,13 @@ Obtaining HDF5 source code
|
||||
and put it in "myhdfstuff".
|
||||
Uncompress the file. There should be a hdf5-2."X"."Y" folder.
|
||||
|
||||
3. Obtain HDF5 plugin source from Github
|
||||
development branch: https://github.com/HDFGroup/hdf5_plugins
|
||||
Or let the CMake build process download the plugins for you with
|
||||
the following options:
|
||||
HDF5_ALLOW_EXTERNAL_SUPPORT:STRING="GIT"(or "TGZ")
|
||||
HDF5_ENABLE_PLUGIN_SUPPORT:BOOL=ON
|
||||
|
||||
CMake version
|
||||
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.18,
|
||||
@@ -44,6 +51,10 @@ Note:
|
||||
the CMake variable, CMAKE_INSTALL_PREFIX. Users of build scripts
|
||||
will use the INSTALLDIR option.
|
||||
|
||||
Note:
|
||||
See the CMake documentation for more information on setting the
|
||||
logging levels:
|
||||
https://cmake.org/cmake/help/latest/variable/CMAKE_MESSAGE_LOG_LEVEL.html
|
||||
|
||||
========================================================================
|
||||
II. Quick Step Building HDF5 Libraries with CMake Script Mode
|
||||
@@ -52,7 +63,12 @@ This short set of instructions is written for users who want to quickly
|
||||
build the HDF5 C, C++ and Fortran shared libraries and tools
|
||||
from the HDF5 source code package using the CMake tools. This procedure
|
||||
will use the default settings in the config/cmake/cacheinit.cmake file.
|
||||
HDF Group recommends using the ctest script mode to build HDF5.
|
||||
The HDF Group recommends using the ctest script mode to build HDF5.
|
||||
|
||||
NOTE: if you are using CMake 3.24 or later, you can use the presets process.
|
||||
The CMakePresets.json file in the source directory will configure, build, test,
|
||||
and package HDF5 with the same options that are set in the cacheinit.cmake file.
|
||||
see Section X: Using CMakePresets.json for compiling
|
||||
|
||||
-------------------------------------------------------------------------
|
||||
-------------------------------------------------------------------------
|
||||
@@ -1055,53 +1071,74 @@ References:
|
||||
========================================================================
|
||||
X: Using CMakePresets.json for compiling
|
||||
========================================================================
|
||||
Quick Start Presets
|
||||
You want to build HDF5 with CMake, but there are so many options to consider.
|
||||
|
||||
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.
|
||||
Solution
|
||||
-------------------------------
|
||||
CMake introduced presets in version 3.19. HDF Group provides a file in the source,
|
||||
CMakePresets.json, requiring CMake 3.24 or higher, that will build HDF5 with the
|
||||
options for building a typical shared library with the common languages for a
|
||||
platform. The features include building the tools, examples, plugins, and the
|
||||
shared and static libraries.
|
||||
|
||||
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.
|
||||
The CMakePresets.json file is located in the root directory of the HDF5 source.
|
||||
It is from here you will execute the cmake command to build HDF5. The following
|
||||
example shows how to build HDF5 with the CMakePresets.json file:
|
||||
change directory to the hdf5 source folder
|
||||
execute "cmake --workflow --preset ci-StdShar-<compiler-type> --fresh"
|
||||
where "<compiler-type>" is GNUC or MSVC or Clang
|
||||
|
||||
See CMake documentation for details: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html
|
||||
The above example will create a "build" folder in the source parent directory, which
|
||||
will contain the results of the build, including installation package files.
|
||||
|
||||
Discussion
|
||||
-------------------------------
|
||||
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 static libraries and tools. Other configurations
|
||||
used for inheriting settings are in the included json file in "config/cmake-presets/hidden-presets.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 static 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
|
||||
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 --preset ci-StdShar-<compiler-type>
|
||||
cmake --build --preset ci-StdShar-<compiler-type>
|
||||
ctest --preset ci-StdShar-<compiler-type>
|
||||
cpack --preset ci-StdShar-<compiler-type>
|
||||
Using individual command presets (where <compiler-type> is GNUC or MSVC or Clang):
|
||||
change directory to the hdf5 source folder
|
||||
cmake --preset ci-StdShar-<compiler-type>
|
||||
cmake --build --preset ci-StdShar-<compiler-type>
|
||||
ctest --preset ci-StdShar-<compiler-type>
|
||||
cpack --preset ci-StdShar-<compiler-type>
|
||||
|
||||
Using the workflow preset to configure, build, test and package the standard configuration:
|
||||
change directory to the hdf5 source folder
|
||||
execute "cmake --workflow --preset ci-StdShar-<compiler-type> --fresh"
|
||||
where <compiler-type> is GNUC or MSVC or Clang
|
||||
Using the workflow preset to configure, build, test and package the standard configuration:
|
||||
change directory to the hdf5 source folder
|
||||
execute "cmake --workflow --preset 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.
|
||||
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:
|
||||
......
|
||||
For instance, to change the support files to use a local directory, edit CMakeUserPresets.json:
|
||||
{
|
||||
"name": "my-base-tgz",
|
||||
"hidden": true,
|
||||
@@ -1135,10 +1172,8 @@ For instance, to change the support files to use a local directory, edit CMakeUs
|
||||
"my-StdExamples"
|
||||
]
|
||||
}
|
||||
......
|
||||
|
||||
|
||||
Then you can change or add options for your specific case.
|
||||
Then you can change or add options for your specific case.
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user