From 9b5d9680af8401528bb8c3b6d2b4c3cf30ccec5b Mon Sep 17 00:00:00 2001 From: Dana Robinson <43805+derobins@users.noreply.github.com> Date: Mon, 15 Jul 2024 05:38:13 -0700 Subject: [PATCH 01/20] Clean up Fortran __float128 configure-time checks (#4649) * Always use DECIMAL_DIG instead of LDBL_DIG. This was controlled by an ifdef that is always true in C99 or greater It's confusing to use float.h C constants as variable names in configure.ac and the PAC_FC_LDBL_DIG macro. * Directly compare MY_FLT128_DIG and MY_LDBL_DIG * Make uniform across CMake and Autotools * Don't export quadmath.h variables to H5pubconf.h --- config/cmake/ConfigureChecks.cmake | 102 +++++++++++++++++------------ config/cmake/H5pubconf.h.in | 11 +--- config/cmake/HDF5UseFortran.cmake | 23 ++++--- config/cmake/HDFTests.c | 12 ++++ configure.ac | 88 +++++++++++++++++++------ fortran/test/tH5T_F03.F90 | 4 -- m4/aclocal_fc.m4 | 38 ++++++----- 7 files changed, 171 insertions(+), 107 deletions(-) diff --git a/config/cmake/ConfigureChecks.cmake b/config/cmake/ConfigureChecks.cmake index af2d13e5180..e7e3c27ff75 100644 --- a/config/cmake/ConfigureChecks.cmake +++ b/config/cmake/ConfigureChecks.cmake @@ -132,11 +132,15 @@ endif () ## Check for non-standard extension quadmath.h -CHECK_INCLUDE_FILES(quadmath.h C_HAVE_QUADMATH) -if (C_HAVE_QUADMATH) - set(${HDF_PREFIX}_HAVE_QUADMATH_H 1) +# gcc puts symbols like FLT128_DIG in quadmath.h instead of float.h, so +# check for that. This is only used by the build system and doesn't need +# to be exported to H5pubconf.h. +CHECK_INCLUDE_FILES("quadmath.h" INCLUDE_QUADMATH_H) +# Convert TRUE/FALSE to 0/1 for preprocessor values in test code, below +if (${INCLUDE_QUADMATH_H}) + set(C_INCLUDE_QUADMATH_H 1) else () - set(${HDF_PREFIX}_HAVE_QUADMATH_H 0) + set(C_INCLUDE_QUADMATH_H 0) endif () if (CYGWIN) @@ -646,22 +650,38 @@ endif() #----------------------------------------------------------------------------- if (HDF5_BUILD_FORTRAN) - HDF_CHECK_TYPE_SIZE(__float128 _SIZEOF___FLOAT128) - if (_SIZEOF___FLOAT128) - set (${HDF_PREFIX}_HAVE_FLOAT128 1) - set (${HDF_PREFIX}_SIZEOF___FLOAT128 ${_SIZEOF___FLOAT128}) - else () - set (${HDF_PREFIX}_HAVE_FLOAT128 0) - set (${HDF_PREFIX}_SIZEOF___FLOAT128 0) - endif () + # ---------------------------------------------------------------------- + # __float128 checks + # + # If __float128 exists and we can determine its precision, we will use + # it in the Fortran interface. The checks for this require that the + # precision be specified via a symbol named FLT128_DIG, which might be + # found in quadmath.h. + # + # The checks here are based on the GNU __float128 extension type from + # libquadmath, which is now part of gcc. Other compilers (clang, Intel) + # also expose __float128 and/or __float128 may be an alias for some + # other 128-bit floating point type. + # + # 128-bit floating-point math is usually handled in software and is thus + # orders of magnitude slower than hardware-supported floating-point math. + # - HDF_CHECK_TYPE_SIZE(_Quad _SIZEOF__QUAD) - if (NOT _SIZEOF__QUAD) - set (${HDF_PREFIX}_SIZEOF__QUAD 0) + #----------------------------------------------------------------------------- + # Is the __float128 type available? + #----------------------------------------------------------------------------- + HDF_FUNCTION_TEST (HAVE___FLOAT128) + # Convert TRUE/FALSE to 0/1 for preprocessor values in test code, below + if (${HAVE___FLOAT128}) + set(C_HAVE_FLOAT128 1) else () - set (${HDF_PREFIX}_SIZEOF__QUAD ${_SIZEOF__QUAD}) + set(C_HAVE_FLOAT128 0) endif () + #----------------------------------------------------------------------------- + # Get the max decimal precision in C, checking both long double and + # __float128 (if available) + #----------------------------------------------------------------------------- if (NOT CMAKE_CROSSCOMPILING) #----------------------------------------------------------------------------- # The provided CMake C macros don't provide a general compile/run function @@ -682,7 +702,6 @@ if (HDF5_BUILD_FORTRAN) TRY_RUN (RUN_RESULT_VAR COMPILE_RESULT_VAR ${CMAKE_BINARY_DIR} ${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CMakeTmp/testCCompiler1.c - COMPILE_DEFINITIONS "-D_SIZEOF___FLOAT128=${H5_SIZEOF___FLOAT128};-D_HAVE_QUADMATH_H=${H5_HAVE_QUADMATH_H}" COMPILE_OUTPUT_VARIABLE COMPILEOUT ${_RUN_OUTPUT_VARIABLE} OUTPUT_VAR ) @@ -719,43 +738,42 @@ if (HDF5_BUILD_FORTRAN) " #include \n\ #include \n\ -#define CHECK_FLOAT128 _SIZEOF___FLOAT128\n\ -#if CHECK_FLOAT128!=0\n\ -#if _HAVE_QUADMATH_H!=0\n\ -#include \n\ -#endif\n\ -#ifdef FLT128_DIG\n\ -#define C_FLT128_DIG FLT128_DIG\n\ -#else\n\ -#define C_FLT128_DIG 0\n\ -#endif\n\ +#if ${C_HAVE_FLOAT128}\n\ +# if ${C_INCLUDE_QUADMATH_H}\n\ +# include \n\ +# endif\n\ +# ifdef FLT128_DIG\n\ +# define C_FLT128_DIG FLT128_DIG\n\ +# else\n\ +# define C_FLT128_DIG 0\n\ +# endif\n\ #else\n\ -#define C_FLT128_DIG 0\n\ +# define C_FLT128_DIG 0\n\ #endif\n\ -#if defined (__STDC_VERSION__) && __STDC_VERSION__ >= 199901L\n\ #define C_LDBL_DIG DECIMAL_DIG\n\ -#else\n\ -#define C_LDBL_DIG LDBL_DIG\n\ -#endif\n\nint main(void) {\nprintf(\"\\%d\\\;\\%d\\\;\", C_LDBL_DIG, C_FLT128_DIG)\\\;\n\nreturn 0\\\;\n}\n - " +\n\ +int main(void) {\nprintf(\"\\%d\\\;\\%d\\\;\", C_LDBL_DIG, C_FLT128_DIG)\\\;\n\nreturn 0\\\;\n}\n + " ) C_RUN ("maximum decimal precision for C" ${PROG_SRC} PROG_RES PROG_OUTPUT4) message (STATUS "Testing maximum decimal precision for C - ${PROG_OUTPUT4}") - # dnl The output from the above program will be: - # dnl -- long double decimal precision -- __float128 decimal precision + # The output from the above program will be: + # -- long double decimal precision -- __float128 decimal precision - list (GET PROG_OUTPUT4 0 H5_LDBL_DIG) - list (GET PROG_OUTPUT4 1 H5_FLT128_DIG) + list (GET PROG_OUTPUT4 0 MY_LDBL_DIG) + list (GET PROG_OUTPUT4 1 MY_FLT128_DIG) - if (${HDF_PREFIX}_SIZEOF___FLOAT128 EQUAL "0" OR FLT128_DIG EQUAL "0") - set (${HDF_PREFIX}_HAVE_FLOAT128 0) - set (${HDF_PREFIX}_SIZEOF___FLOAT128 0) - set (_PAC_C_MAX_REAL_PRECISION ${H5_LDBL_DIG}) + # Set configure output and behavior + if (${HAVE___FLOAT128} AND (${MY_FLT128_DIG} GREATER ${MY_LDBL_DIG})) + set (${HDF_PREFIX}_HAVE_FLOAT128 1) + set (_PAC_C_MAX_REAL_PRECISION ${MY_FLT128_DIG}) else () - set (_PAC_C_MAX_REAL_PRECISION ${H5_FLT128_DIG}) + # No __float128 or the precision of __float128 <= that of long double + set (_PAC_C_MAX_REAL_PRECISION ${MY_LDBL_DIG}) endif () + if (NOT ${_PAC_C_MAX_REAL_PRECISION}) set (${HDF_PREFIX}_PAC_C_MAX_REAL_PRECISION 0) else () diff --git a/config/cmake/H5pubconf.h.in b/config/cmake/H5pubconf.h.in index c6e3a619162..2530a95830d 100644 --- a/config/cmake/H5pubconf.h.in +++ b/config/cmake/H5pubconf.h.in @@ -146,7 +146,7 @@ /* Determine if _Float16 is available */ #cmakedefine H5_HAVE__FLOAT16 @H5_HAVE__FLOAT16@ -/* Determine if __float128 is available */ +/* Determine if __float128 will be used in the Fortran wrappers */ #cmakedefine H5_HAVE_FLOAT128 @H5_HAVE_FLOAT128@ /* Define to 1 if you have the `flock' function. */ @@ -270,9 +270,6 @@ /* Define to 1 if you have the header file. */ #cmakedefine H5_HAVE_PWD_H @H5_HAVE_PWD_H@ -/* Define to 1 if you have the header file. */ -#cmakedefine H5_HAVE_QUADMATH_H @H5_HAVE_QUADMATH_H@ - /* Define whether the Read-Only S3 virtual file driver (VFD) should be compiled */ #cmakedefine H5_HAVE_ROS3_VFD @H5_HAVE_ROS3_VFD@ @@ -586,15 +583,9 @@ /* The size of `unsigned', as computed by sizeof. */ #cmakedefine H5_SIZEOF_UNSIGNED @H5_SIZEOF_UNSIGNED@ -/* The size of `_Quad', as computed by sizeof. */ -#define H5_SIZEOF__QUAD @H5_SIZEOF__QUAD@ - /* The size of `_Float16', as computed by sizeof. */ #define H5_SIZEOF__FLOAT16 @H5_SIZEOF__FLOAT16@ -/* The size of `__float128', as computed by sizeof. */ -#define H5_SIZEOF___FLOAT128 @H5_SIZEOF___FLOAT128@ - /* Define if strict file format checks are enabled */ #cmakedefine H5_STRICT_FORMAT_CHECKS @H5_STRICT_FORMAT_CHECKS@ diff --git a/config/cmake/HDF5UseFortran.cmake b/config/cmake/HDF5UseFortran.cmake index 98fa75ecfc9..ce33c7036e3 100644 --- a/config/cmake/HDF5UseFortran.cmake +++ b/config/cmake/HDF5UseFortran.cmake @@ -363,13 +363,13 @@ set (PROG_SRC3 " ) FORTRAN_RUN ("SIZEOF NATIVE KINDs" ${PROG_SRC3} XX YY PAC_SIZEOF_NATIVE_KINDS_RESULT PROG_OUTPUT3) -# dnl The output from the above program will be: -# dnl -- LINE 1 -- sizeof INTEGER -# dnl -- LINE 2 -- kind of INTEGER -# dnl -- LINE 3 -- sizeof REAL -# dnl -- LINE 4 -- kind of REAL -# dnl -- LINE 5 -- sizeof DOUBLE PRECISION -# dnl -- LINE 6 -- kind of DOUBLE PRECISION +# The output from the above program will be: +# -- LINE 1 -- sizeof INTEGER +# -- LINE 2 -- kind of INTEGER +# -- LINE 3 -- sizeof REAL +# -- LINE 4 -- kind of REAL +# -- LINE 5 -- sizeof DOUBLE PRECISION +# -- LINE 6 -- kind of DOUBLE PRECISION # # Convert the string to a list of strings by replacing the carriage return with a semicolon string (REGEX REPLACE "[\r\n]+" ";" PROG_OUTPUT3 "${PROG_OUTPUT3}") @@ -402,11 +402,10 @@ endif () set (${HDF_PREFIX}_FORTRAN_SIZEOF_LONG_DOUBLE ${${HDF_PREFIX}_SIZEOF_LONG_DOUBLE}) -# remove the invalid kind from the list -if (NOT(${${HDF_PREFIX}_SIZEOF___FLOAT128} EQUAL 0)) - if (NOT(${${HDF_PREFIX}_SIZEOF___FLOAT128} EQUAL ${max_real_fortran_sizeof}) - AND NOT(${${HDF_PREFIX}_FORTRAN_SIZEOF_LONG_DOUBLE} EQUAL ${max_real_fortran_sizeof}) - # account for the fact that the C compiler can have 16-byte __float128 and the fortran compiler only has 8-byte doubles, +# Remove the invalid kind from the list +if (${${HDF_PREFIX}_HAVE_FLOAT128}) + if (NOT(16 EQUAL ${max_real_fortran_sizeof}) AND NOT(${${HDF_PREFIX}_FORTRAN_SIZEOF_LONG_DOUBLE} EQUAL ${max_real_fortran_sizeof}) + # Account for the fact that the C compiler can have 16-byte __float128 and the fortran compiler only has 8-byte doubles, # so we don't want to remove the 8-byte fortran doubles. AND NOT(${PAC_FORTRAN_NATIVE_DOUBLE_SIZEOF} EQUAL ${max_real_fortran_sizeof})) message (WARNING " diff --git a/config/cmake/HDFTests.c b/config/cmake/HDFTests.c index 8d0e78f46b7..042a34dfd51 100644 --- a/config/cmake/HDFTests.c +++ b/config/cmake/HDFTests.c @@ -14,6 +14,18 @@ /* A simple test program to see if a function "works" */ #define SIMPLE_TEST(x) int main(void){ x; return 0; } +#ifdef HAVE___FLOAT128 + +/* Check if __float128 works (only used in the Fortran interface) */ +int +main () +{ + __float128 x; + + return 0; +} + +#endif /* HAVE___FLOAT128 */ #ifdef HAVE_BUILTIN_EXPECT diff --git a/configure.ac b/configure.ac index 1cf3168b815..cfbab793c98 100644 --- a/configure.ac +++ b/configure.ac @@ -793,30 +793,76 @@ AC_MSG_RESULT([$HDF_FORTRAN]) if test "X$HDF_FORTRAN" = "Xyes"; then -## ---------------------------------------------------------------------- -## Check for non-standard extension __FLOAT128 -## - HAVE_FLOAT128=0 - HAVE_QUADMATH=0 - FLT128_DIG=0 - LDBL_DIG=0 - - AC_CHECK_SIZEOF([__float128]) - AC_CHECK_SIZEOF([_Quad]) - AC_CHECK_HEADERS([quadmath.h], [HAVE_QUADMATH=1], []) + ## ---------------------------------------------------------------------- + ## __float128 checks + ## + ## If __float128 exists and we can determine its precision, we will use + ## it in the Fortran interface. The checks for this require that the + ## precision be specified via a symbol named FLT128_DIG, which might be + ## found in quadmath.h. + ## + ## The checks here are based on the GNU __float128 extension type from + ## libquadmath, which is now part of gcc. Other compilers (clang, Intel) + ## also expose __float128 and/or __float128 may be an alias for some + ## other 128-bit floating point type. + ## + ## 128-bit floating-point math is usually handled in software and is thus + ## orders of magnitude slower than hardware-supported floating-point math. + ## + AC_MSG_CHECKING([if __float128 exists]) + AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[]],[[__float128 x; return 0;]])], + [HAVE___FLOAT128=1; AC_MSG_RESULT([yes])], + [HAVE___FLOAT128=0; AC_MSG_RESULT([no])] + ) + + ## gcc puts symbols like FLT128_DIG in quadmath.h instead of float.h, + ## so check for that before running the precision macro. Note that + ## using AC_CHECK_HEADER instead of AC_CHECK_HEADERS keeps the + ## H5_HAVE_QUADMATH_H symbol out of the public config header. + ## + AC_CHECK_HEADER([quadmath.h], [INCLUDE_QUADMATH_H=1], [INCLUDE_QUADMATH_H=0]) + + ## ---------------------------------------------------------------------- + ## Get the max decimal precision in C, checking both long double and + ## __float128 (if available) + ## + AC_MSG_CHECKING([maximum decimal precision for C]) + + MY_FLT128_DIG=0 + MY_LDBL_DIG=0 + + ## Macro to compare long double and __float128 to see which has higher precision PAC_FC_LDBL_DIG + ## Set results + if test "$MY_FLT128_DIG" -gt "$MY_LDBL_DIG" ; then + PAC_C_MAX_REAL_PRECISION=$MY_FLT128_DIG + PRECISION_TYPE="(__float128)" + else + PAC_C_MAX_REAL_PRECISION=$MY_LDBL_DIG + PRECISION_TYPE="(long double)" + fi + AC_MSG_RESULT([$PAC_C_MAX_REAL_PRECISION $PRECISION_TYPE]) + + ## Store results in config file AC_SUBST([PAC_C_MAX_REAL_PRECISION]) + AC_DEFINE_UNQUOTED([PAC_C_MAX_REAL_PRECISION], $PAC_C_MAX_REAL_PRECISION, [Determine the maximum decimal precision in C]) + + ## Are we going to use __float128? + AC_MSG_CHECKING([if __float128 will be used in the Fortran wrappers]) - if test "$ac_cv_sizeof___float128" != 0 && test "$FLT128_DIG" != 0 ; then - AC_DEFINE([HAVE_FLOAT128], [1], [Determine if __float128 is available]) - PAC_C_MAX_REAL_PRECISION=$FLT128_DIG + if test "$MY_FLT128_DIG" -gt "$MY_LDBL_DIG" ; then + AC_MSG_RESULT([yes]) + AC_DEFINE([HAVE_FLOAT128], [1], [Determine if __float128 will be used in the Fortran wrappers]) else - PAC_C_MAX_REAL_PRECISION=$LDBL_DIG + ## Can't use __float128, but write an undef line anyway + AC_MSG_RESULT([no]) + AH_TEMPLATE([HAVE_FLOAT128], [Determine if __float128 will be used in the Fortran wrappers]) fi - AC_DEFINE_UNQUOTED([PAC_C_MAX_REAL_PRECISION], $PAC_C_MAX_REAL_PRECISION, [Determine the maximum decimal precision in C]) - AC_MSG_RESULT([$PAC_C_MAX_REAL_PRECISION]) + ## ---------------------------------------------------------------------- + ## Define interface version + ## VERS_MAJOR=`cat $srcdir/src/H5public.h | sed -n 's/^#define H5_VERS_MAJOR //p'` VERS_MINOR=`cat $srcdir/src/H5public.h | sed -n 's/^#define H5_VERS_MINOR //p'` VERS_RELEASE=`cat $srcdir/src/H5public.h | sed -n 's/^#define H5_VERS_RELEASE //p'` @@ -824,10 +870,10 @@ if test "X$HDF_FORTRAN" = "Xyes"; then AC_DEFINE_UNQUOTED([VERS_MINOR_TMP], $VERS_MINOR, [Define minor library version]) AC_DEFINE_UNQUOTED([VERS_RELEASE_TMP], $VERS_RELEASE, [Define release library version]) -## We will output an include file for Fortran, H5config_f.inc which -## contains various configure definitions used by the Fortran Library. -## Prepend H5_ to all macro names. This avoids name conflict between HDF5 macro -## names and those generated by another software package that uses the HDF5 library. + ## We will output an include file for Fortran, H5config_f.inc which + ## contains various configure definitions used by the Fortran Library. + ## Prepend H5_ to all macro names. This avoids name conflict between HDF5 macro + ## names and those generated by another software package that uses the HDF5 library. AC_CONFIG_HEADERS([fortran/src/H5config_f.inc], [cat fortran/src/H5config_f.inc | sed '1d;s%^/\* \(.*\) \*/%\1%;s/#define /#define H5_/;s/#undef /#undef H5_/' >fortran/src/H5config_f.inc.tmp; sed -i 's\_TMP\\g' fortran/src/H5config_f.inc.tmp; mv -f fortran/src/H5config_f.inc.tmp fortran/src/H5config_f.inc]) diff --git a/fortran/test/tH5T_F03.F90 b/fortran/test/tH5T_F03.F90 index a59cd73f751..e7a3797e37e 100644 --- a/fortran/test/tH5T_F03.F90 +++ b/fortran/test/tH5T_F03.F90 @@ -1090,10 +1090,8 @@ SUBROUTINE test_h5kind_to_type(total_error) CALL check("H5Dcreate_f",error, total_error) CALL H5Dcreate_f(file_id, dsetnamer8, h5kind_to_type(real_kind_15,H5_REAL_KIND), dspace_id, dset_idr8, error) CALL check("H5Dcreate_f",error, total_error) -!#ifdef H5_HAVE_FLOAT128 CALL H5Dcreate_f(file_id, dsetnamer16, h5kind_to_type(real_kind_31,H5_REAL_KIND), dspace_id, dset_idr16, error) CALL check("H5Dcreate_f",error, total_error) -!#endif ! ! Write the dataset. ! @@ -1123,11 +1121,9 @@ SUBROUTINE test_h5kind_to_type(total_error) f_ptr = C_LOC(dset_data_r15(1)) CALL h5dwrite_f(dset_idr8, h5kind_to_type(real_kind_15,H5_REAL_KIND), f_ptr, error) CALL check("H5Dwrite_f",error, total_error) -!#ifdef H5_HAVE_FLOAT128 f_ptr = C_LOC(dset_data_r31(1)) CALL h5dwrite_f(dset_idr16, h5kind_to_type(real_kind_31,H5_REAL_KIND), f_ptr, error) CALL check("H5Dwrite_f",error, total_error) -!#endif ! ! Close the file ! diff --git a/m4/aclocal_fc.m4 b/m4/aclocal_fc.m4 index cfcfbcf7ca2..610ee300611 100644 --- a/m4/aclocal_fc.m4 +++ b/m4/aclocal_fc.m4 @@ -528,37 +528,39 @@ FCFLAGS=$saved_FCFLAGS AC_LANG_POP([Fortran]) ]) +dnl Check for the maximum decimal precision for C +dnl +dnl Depends on if __float128 and/or quadmath.h exist. We only support 128-bit +dnl floats that work like GNU's quadmath.h __float128 type, which have the +dnl precision stored in a symbol named FLT128_DIG. +dnl +dnl The MY_(LDBL|FLT128)_DIG variables are from configure.ac +dnl AC_DEFUN([PAC_FC_LDBL_DIG],[ -AC_MSG_CHECKING([maximum decimal precision for C]) AC_LANG_CONFTEST([ AC_LANG_PROGRAM([ #include #include - #define CHECK_FLOAT128 $ac_cv_sizeof___float128 - #if CHECK_FLOAT128!=0 - # if $HAVE_QUADMATH!=0 - #include - # endif - # ifdef FLT128_DIG - #define C_FLT128_DIG FLT128_DIG - # else - #define C_FLT128_DIG 0 - # endif + #if $HAVE___FLOAT128 != 0 + # if $INCLUDE_QUADMATH_H != 0 + # include + # endif + # ifdef FLT128_DIG + # define C_FLT128_DIG FLT128_DIG + # else + # define C_FLT128_DIG 0 + # endif #else - #define C_FLT128_DIG 0 + # define C_FLT128_DIG 0 #endif - #if defined (__STDC_VERSION__) && __STDC_VERSION__ >= 199901L #define C_LDBL_DIG DECIMAL_DIG - #else - #define C_LDBL_DIG LDBL_DIG - #endif ],[[ fprintf(stderr, "%d\n%d\n", C_LDBL_DIG, C_FLT128_DIG); ]]) ]) AC_RUN_IFELSE([],[ - LDBL_DIG=$(./conftest$EXEEXT 2>&1 | sed -n '1p') - FLT128_DIG=$(./conftest$EXEEXT 2>&1 | sed -n '2p') + MY_LDBL_DIG=$(./conftest$EXEEXT 2>&1 | sed -n '1p') + MY_FLT128_DIG=$(./conftest$EXEEXT 2>&1 | sed -n '2p') ],[ AC_MSG_ERROR([C program fails to build or run!]) ],[]) From 4cbdf1a5f812d3b5d3329badbc457a8955296de3 Mon Sep 17 00:00:00 2001 From: Gerd Heber Date: Mon, 15 Jul 2024 08:11:58 -0500 Subject: [PATCH 02/20] Feature/awesome (#4604) * Added Doxygen Awesome and fixed a few quirks. * Fixed unterminated strings. * Added Doxygen Awesome by copy. --- configure.ac | 2 +- doxygen/CMakeLists.txt | 2 +- doxygen/Doxyfile.in | 2 +- doxygen/aliases | 4 +- doxygen/dox/About.dox | 14 +- doxygen/dox/Overview.dox | 14 - doxygen/dox/TechnicalNotes.dox | 2 + doxygen/dox/UsersGuide.dox | 7 - doxygen/doxygen-awesome.css | 2677 +++++++++++++++++ .../examples/DebuggingHDF5Applications.html | 6 +- doxygen/examples/FileFormat.html | 26 +- doxygen/examples/FileImageOps.html | 3 +- doxygen/examples/H5.format.1.0.html | 3 +- doxygen/examples/H5.format.1.1.html | 5 +- doxygen/examples/H5.format.2.0.html | 31 +- doxygen/examples/H5.format.html | 32 +- doxygen/hdf5_header.html | 34 +- doxygen/hdf5doxy.css | 175 +- doxygen/hdf5doxy_layout.xml | 14 +- 19 files changed, 2773 insertions(+), 280 deletions(-) create mode 100644 doxygen/doxygen-awesome.css diff --git a/configure.ac b/configure.ac index cfbab793c98..a150c4930f2 100644 --- a/configure.ac +++ b/configure.ac @@ -1593,7 +1593,7 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then DOXYGEN_LAYOUT_FILE='$(SRCDIR)/doxygen/hdf5doxy_layout.xml' DOXYGEN_HTML_HEADER='$(SRCDIR)/doxygen/hdf5_header.html' DOXYGEN_HTML_FOOTER='$(SRCDIR)/doxygen/hdf5_footer.html' - DOXYGEN_HTML_EXTRA_STYLESHEET='$(SRCDIR)/doxygen/hdf5doxy.css' + DOXYGEN_HTML_EXTRA_STYLESHEET='$(SRCDIR)/doxygen/hdf5doxy.css $(SRCDIR)/doxygen/doxygen-awesome.css' DOXYGEN_HTML_EXTRA_FILES='$(SRCDIR)/doxygen/hdf5_navtree_hacks.js' DOXYGEN_TAG_FILE=hdf5.tag DOXYGEN_SERVER_BASED_SEARCH=NO diff --git a/doxygen/CMakeLists.txt b/doxygen/CMakeLists.txt index a3ee438cb8a..ea9946bf694 100644 --- a/doxygen/CMakeLists.txt +++ b/doxygen/CMakeLists.txt @@ -21,7 +21,7 @@ if (DOXYGEN_FOUND) set (DOXYGEN_LAYOUT_FILE ${HDF5_DOXYGEN_DIR}/hdf5doxy_layout.xml) set (DOXYGEN_HTML_HEADER ${HDF5_DOXYGEN_DIR}/hdf5_header.html) set (DOXYGEN_HTML_FOOTER ${HDF5_DOXYGEN_DIR}/hdf5_footer.html) - set (DOXYGEN_HTML_EXTRA_STYLESHEET ${HDF5_DOXYGEN_DIR}/hdf5doxy.css) + set (DOXYGEN_HTML_EXTRA_STYLESHEET "${HDF5_DOXYGEN_DIR}/hdf5doxy.css ${HDF5_DOXYGEN_DIR}/doxygen-awesome.css") set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js") set (DOXYGEN_TAG_FILE ${HDF5_BINARY_DIR}/hdf5.tag) set (DOXYGEN_SERVER_BASED_SEARCH NO) diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index 29033f5de21..8d059bc8732 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -1283,7 +1283,7 @@ ECLIPSE_DOC_ID = org.doxygen.Project # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -DISABLE_INDEX = YES +DISABLE_INDEX = NO # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index # structure should be generated to display hierarchical information. If the tag diff --git a/doxygen/aliases b/doxygen/aliases index fd0afb5d54e..19656fac29b 100644 --- a/doxygen/aliases +++ b/doxygen/aliases @@ -387,8 +387,8 @@ ALIASES += str_pad_type="
#H5T_STR_NULLTERM0Null ALIASES += see_virtual=" \see Supporting Functions: H5Pget_layout(), H5Pset_layout(), H5Sget_regular_hyperslab(), H5Sis_regular_hyperslab(), H5Sselect_hyperslab() \see VDS Functions: H5Pget_virtual_count(), H5Pget_virtual_dsetname(), H5Pget_virtual_filename(), H5Pget_virtual_prefix(), H5Pget_virtual_printf_gap(), H5Pget_virtual_srcspace(), H5Pget_virtual_view(), H5Pget_virtual_vspace(), H5Pset_virtual(), H5Pset_virtual_prefix(), H5Pset_virtual_printf_gap(), H5Pset_virtual_view()" ALIASES += obj_info_fields="
FlagPurpose
#H5O_INFO_BASICFill in the fileno, addr, type, and rc fields
#H5O_INFO_TIMEFill in the atime, mtime, ctime, and btime fields
#H5O_INFO_NUM_ATTRS Fill in the num_attrs field
#H5O_INFO_HDRFill in the num_attrs field
#H5O_INFO_META_SIZEFill in the meta_size field
#H5O_INFO_ALL#H5O_INFO_BASIC | #H5O_INFO_TIME | #H5O_INFO_NUM_ATTRS | #H5O_INFO_HDR | #H5O_INFO_META_SIZE
" -ALIASES += details_namelen{2}="Up to \p size characters of the \1 name are returned in \p name; additional characters, if any, are not returned to the user application.\n\n If the length of the \1 name, which determines the required value of \p size, is unknown, a preliminary call to \2() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the \1 name. That value, plus 1 for a NULL terminator, must then be assigned to \p size for a second \2() call, which will retrieve the actual \1 name. -ALIASES += details_namelen_plusone{2}="Up to \p size characters of the \1 name are returned in \p name; additional characters, if any, are not returned to the user application.\n\n If the length of the \1 name, which determines the required value of \p size, is unknown, a preliminary call to \2() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the \1 name plus 1 for a NULL terminator. That value must then be assigned to \p size for a second \2() call, which will retrieve the actual \1 name. +ALIASES += details_namelen{2}="Up to \p size characters of the \1 name are returned in \p name; additional characters, if any, are not returned to the user application.\n\n If the length of the \1 name, which determines the required value of \p size, is unknown, a preliminary call to \2() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the \1 name. That value, plus 1 for a NULL terminator, must then be assigned to \p size for a second \2() call, which will retrieve the actual \1 name." +ALIASES += details_namelen_plusone{2}="Up to \p size characters of the \1 name are returned in \p name; additional characters, if any, are not returned to the user application.\n\n If the length of the \1 name, which determines the required value of \p size, is unknown, a preliminary call to \2() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the \1 name plus 1 for a NULL terminator. That value must then be assigned to \p size for a second \2() call, which will retrieve the actual \1 name." ################################################################################ diff --git a/doxygen/dox/About.dox b/doxygen/dox/About.dox index 8b7c141dd1b..d4a1db2bc62 100644 --- a/doxygen/dox/About.dox +++ b/doxygen/dox/About.dox @@ -8,7 +8,9 @@ Please refer to their GitLab reposit and the online version of their Doxygen-based documentation. Not only does Eigen set a standard as a piece of software, but also as an example -of documentation done right. +of documentation done right. And kudos to the +Doxygen Awesome project +for their style sheets. \section about_documentation Documentation about Documentation @@ -114,14 +116,4 @@ be https://\RFCURL/my_great_rfc_name.pdf \endverbatim -\subsection hosting How Do Updates and Changes Get Published? - -Currently, the files underlying this documentation website are stored in an -bucket on AWS S3. The top-level bucket is 
s3://docs.hdfgroup.org/hdf5/
-There are folders for the development branch and all supported release -version. - -Talk to your friendly IT-team if you need write access, or you need someone to -push an updated version for you! - */ \ No newline at end of file diff --git a/doxygen/dox/Overview.dox b/doxygen/dox/Overview.dox index 5ea42c95a4d..c84ce0a9a60 100644 --- a/doxygen/dox/Overview.dox +++ b/doxygen/dox/Overview.dox @@ -20,20 +20,6 @@ while the \link Cookbook \endlink is focused on tasks. The different guide-type documents cover a mix of tasks, concepts, and reference, to help a specific audience succeed. -\par Versions - Version-specific documentation (see the version in the title area) can be found - here: - - HDF5 develop branch (this site) - - HDF5 1.14.x - - HDF5 1.12.x - - HDF5 1.10.x - - HDF5 1.8.x - -\par Search - If you are looking for a specific function, constant, type, etc., use the - search box in the top right-hand corner!\n Otherwise, check out the - \link FTS full-text search\endlink. - \par Offline reading You can download it as an archive for offline reading. diff --git a/doxygen/dox/TechnicalNotes.dox b/doxygen/dox/TechnicalNotes.dox index b1c809417f0..1737b60ab0b 100644 --- a/doxygen/dox/TechnicalNotes.dox +++ b/doxygen/dox/TechnicalNotes.dox @@ -12,6 +12,8 @@ \li \ref VDS \li \ref RELVERSION \li \ref VFL +\li HDF5 Library Architecture Overview +\li \ref VOL_Connector */ diff --git a/doxygen/dox/UsersGuide.dox b/doxygen/dox/UsersGuide.dox index ca478e41ec2..55a1ca134b0 100644 --- a/doxygen/dox/UsersGuide.dox +++ b/doxygen/dox/UsersGuide.dox @@ -1,12 +1,5 @@ /** \page UG HDF5 User Guide -
-HDF5 Release 1.14 - -\image html HDFG-logo.png "The HDF Group" - -
- \ref sec_data_model \li \ref subsec_data_model_intro \li \ref subsec_data_model_abstract diff --git a/doxygen/doxygen-awesome.css b/doxygen/doxygen-awesome.css new file mode 100644 index 00000000000..a2715e268c5 --- /dev/null +++ b/doxygen/doxygen-awesome.css @@ -0,0 +1,2677 @@ +/** + +Doxygen Awesome +https://github.com/jothepro/doxygen-awesome-css + +MIT License + +Copyright (c) 2021 - 2023 jothepro + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +*/ + +html { + /* primary theme color. This will affect the entire websites color scheme: links, arrows, labels, ... */ + --primary-color: #1779c4; + --primary-dark-color: #335c80; + --primary-light-color: #70b1e9; + + /* page base colors */ + --page-background-color: #ffffff; + --page-foreground-color: #2f4153; + --page-secondary-foreground-color: #6f7e8e; + + /* color for all separators on the website: hr, borders, ... */ + --separator-color: #dedede; + + /* border radius for all rounded components. Will affect many components, like dropdowns, memitems, codeblocks, ... */ + --border-radius-large: 8px; + --border-radius-small: 4px; + --border-radius-medium: 6px; + + /* default spacings. Most components reference these values for spacing, to provide uniform spacing on the page. */ + --spacing-small: 5px; + --spacing-medium: 10px; + --spacing-large: 16px; + + /* default box shadow used for raising an element above the normal content. Used in dropdowns, search result, ... */ + --box-shadow: 0 2px 8px 0 rgba(0,0,0,.075); + + --odd-color: rgba(0,0,0,.028); + + /* font-families. will affect all text on the website + * font-family: the normal font for text, headlines, menus + * font-family-monospace: used for preformatted text in memtitle, code, fragments + */ + --font-family: -apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Oxygen,Ubuntu,Cantarell,Fira Sans,Droid Sans,Helvetica Neue,sans-serif; + --font-family-monospace: ui-monospace,SFMono-Regular,SF Mono,Menlo,Consolas,Liberation Mono,monospace; + + /* font sizes */ + --page-font-size: 15.6px; + --navigation-font-size: 14.4px; + --toc-font-size: 13.4px; + --code-font-size: 14px; /* affects code, fragment */ + --title-font-size: 22px; + + /* content text properties. These only affect the page content, not the navigation or any other ui elements */ + --content-line-height: 27px; + /* The content is centered and constraint in it's width. To make the content fill the whole page, set the variable to auto.*/ + --content-maxwidth: 1050px; + --table-line-height: 24px; + --toc-sticky-top: var(--spacing-medium); + --toc-width: 200px; + --toc-max-height: calc(100vh - 2 * var(--spacing-medium) - 85px); + + /* colors for various content boxes: @warning, @note, @deprecated @bug */ + --warning-color: #faf3d8; + --warning-color-dark: #f3a600; + --warning-color-darker: #5f4204; + --note-color: #e4f3ff; + --note-color-dark: #1879C4; + --note-color-darker: #274a5c; + --todo-color: #e4dafd; + --todo-color-dark: #5b2bdd; + --todo-color-darker: #2a0d72; + --deprecated-color: #ecf0f3; + --deprecated-color-dark: #5b6269; + --deprecated-color-darker: #43454a; + --bug-color: #f8d1cc; + --bug-color-dark: #b61825; + --bug-color-darker: #75070f; + --invariant-color: #d8f1e3; + --invariant-color-dark: #44b86f; + --invariant-color-darker: #265532; + + /* blockquote colors */ + --blockquote-background: #f8f9fa; + --blockquote-foreground: #636568; + + /* table colors */ + --tablehead-background: #f1f1f1; + --tablehead-foreground: var(--page-foreground-color); + + /* menu-display: block | none + * Visibility of the top navigation on screens >= 768px. On smaller screen the menu is always visible. + * `GENERATE_TREEVIEW` MUST be enabled! + */ + --menu-display: block; + + --menu-focus-foreground: var(--page-background-color); + --menu-focus-background: var(--primary-color); + --menu-selected-background: rgba(0,0,0,.05); + + + --header-background: var(--page-background-color); + --header-foreground: var(--page-foreground-color); + + /* searchbar colors */ + --searchbar-background: var(--side-nav-background); + --searchbar-foreground: var(--page-foreground-color); + + /* searchbar size + * (`searchbar-width` is only applied on screens >= 768px. + * on smaller screens the searchbar will always fill the entire screen width) */ + --searchbar-height: 33px; + --searchbar-width: 210px; + --searchbar-border-radius: var(--searchbar-height); + + /* code block colors */ + --code-background: #f5f5f5; + --code-foreground: var(--page-foreground-color); + + /* fragment colors */ + --fragment-background: #F8F9FA; + --fragment-foreground: #37474F; + --fragment-keyword: #bb6bb2; + --fragment-keywordtype: #8258b3; + --fragment-keywordflow: #d67c3b; + --fragment-token: #438a59; + --fragment-comment: #969696; + --fragment-link: #5383d6; + --fragment-preprocessor: #46aaa5; + --fragment-linenumber-color: #797979; + --fragment-linenumber-background: #f4f4f5; + --fragment-linenumber-border: #e3e5e7; + --fragment-lineheight: 20px; + + /* sidebar navigation (treeview) colors */ + --side-nav-background: #fbfbfb; + --side-nav-foreground: var(--page-foreground-color); + --side-nav-arrow-opacity: 0; + --side-nav-arrow-hover-opacity: 0.9; + + --toc-background: var(--side-nav-background); + --toc-foreground: var(--side-nav-foreground); + + /* height of an item in any tree / collapsible table */ + --tree-item-height: 30px; + + --memname-font-size: var(--code-font-size); + --memtitle-font-size: 18px; + + --webkit-scrollbar-size: 7px; + --webkit-scrollbar-padding: 4px; + --webkit-scrollbar-color: var(--separator-color); + + --animation-duration: .12s +} + +@media screen and (max-width: 767px) { + html { + --page-font-size: 16px; + --navigation-font-size: 16px; + --toc-font-size: 15px; + --code-font-size: 15px; /* affects code, fragment */ + --title-font-size: 22px; + } +} + +@media (prefers-color-scheme: dark) { + html:not(.light-mode) { + color-scheme: dark; + + --primary-color: #1982d2; + --primary-dark-color: #86a9c4; + --primary-light-color: #4779ac; + + --box-shadow: 0 2px 8px 0 rgba(0,0,0,.35); + + --odd-color: rgba(100,100,100,.06); + + --menu-selected-background: rgba(0,0,0,.4); + + --page-background-color: #1C1D1F; + --page-foreground-color: #d2dbde; + --page-secondary-foreground-color: #859399; + --separator-color: #38393b; + --side-nav-background: #252628; + + --code-background: #2a2c2f; + + --tablehead-background: #2a2c2f; + + --blockquote-background: #222325; + --blockquote-foreground: #7e8c92; + + --warning-color: #3b2e04; + --warning-color-dark: #f1b602; + --warning-color-darker: #ceb670; + --note-color: #163750; + --note-color-dark: #1982D2; + --note-color-darker: #dcf0fa; + --todo-color: #2a2536; + --todo-color-dark: #7661b3; + --todo-color-darker: #ae9ed6; + --deprecated-color: #2e323b; + --deprecated-color-dark: #738396; + --deprecated-color-darker: #abb0bd; + --bug-color: #2e1917; + --bug-color-dark: #ad2617; + --bug-color-darker: #f5b1aa; + --invariant-color: #303a35; + --invariant-color-dark: #76ce96; + --invariant-color-darker: #cceed5; + + --fragment-background: #282c34; + --fragment-foreground: #dbe4eb; + --fragment-keyword: #cc99cd; + --fragment-keywordtype: #ab99cd; + --fragment-keywordflow: #e08000; + --fragment-token: #7ec699; + --fragment-comment: #999999; + --fragment-link: #98c0e3; + --fragment-preprocessor: #65cabe; + --fragment-linenumber-color: #cccccc; + --fragment-linenumber-background: #35393c; + --fragment-linenumber-border: #1f1f1f; + } +} + +/* dark mode variables are defined twice, to support both the dark-mode without and with doxygen-awesome-darkmode-toggle.js */ +html.dark-mode { + color-scheme: dark; + + --primary-color: #1982d2; + --primary-dark-color: #86a9c4; + --primary-light-color: #4779ac; + + --box-shadow: 0 2px 8px 0 rgba(0,0,0,.30); + + --odd-color: rgba(100,100,100,.06); + + --menu-selected-background: rgba(0,0,0,.4); + + --page-background-color: #1C1D1F; + --page-foreground-color: #d2dbde; + --page-secondary-foreground-color: #859399; + --separator-color: #38393b; + --side-nav-background: #252628; + + --code-background: #2a2c2f; + + --tablehead-background: #2a2c2f; + + --blockquote-background: #222325; + --blockquote-foreground: #7e8c92; + + --warning-color: #3b2e04; + --warning-color-dark: #f1b602; + --warning-color-darker: #ceb670; + --note-color: #163750; + --note-color-dark: #1982D2; + --note-color-darker: #dcf0fa; + --todo-color: #2a2536; + --todo-color-dark: #7661b3; + --todo-color-darker: #ae9ed6; + --deprecated-color: #2e323b; + --deprecated-color-dark: #738396; + --deprecated-color-darker: #abb0bd; + --bug-color: #2e1917; + --bug-color-dark: #ad2617; + --bug-color-darker: #f5b1aa; + --invariant-color: #303a35; + --invariant-color-dark: #76ce96; + --invariant-color-darker: #cceed5; + + --fragment-background: #282c34; + --fragment-foreground: #dbe4eb; + --fragment-keyword: #cc99cd; + --fragment-keywordtype: #ab99cd; + --fragment-keywordflow: #e08000; + --fragment-token: #7ec699; + --fragment-comment: #999999; + --fragment-link: #98c0e3; + --fragment-preprocessor: #65cabe; + --fragment-linenumber-color: #cccccc; + --fragment-linenumber-background: #35393c; + --fragment-linenumber-border: #1f1f1f; +} + +body { + color: var(--page-foreground-color); + background-color: var(--page-background-color); + font-size: var(--page-font-size); +} + +body, table, div, p, dl, #nav-tree .label, .title, +.sm-dox a, .sm-dox a:hover, .sm-dox a:focus, #projectname, +.SelectItem, #MSearchField, .navpath li.navelem a, +.navpath li.navelem a:hover, p.reference, p.definition, div.toc li, div.toc h3 { + font-family: var(--font-family); +} + +h1, h2, h3, h4, h5 { + margin-top: 1em; + font-weight: 600; + line-height: initial; +} + +p, div, table, dl, p.reference, p.definition { + font-size: var(--page-font-size); +} + +p.reference, p.definition { + color: var(--page-secondary-foreground-color); +} + +a:link, a:visited, a:hover, a:focus, a:active { + color: var(--primary-color) !important; + font-weight: 500; + background: none; +} + +a.anchor { + scroll-margin-top: var(--spacing-large); + display: block; +} + +/* + Title and top navigation + */ + +#top { + background: var(--header-background); + border-bottom: 1px solid var(--separator-color); +} + +@media screen and (min-width: 768px) { + #top { + display: flex; + flex-wrap: wrap; + justify-content: space-between; + align-items: center; + } +} + +#main-nav { + flex-grow: 5; + padding: var(--spacing-small) var(--spacing-medium); +} + +#titlearea { + width: auto; + padding: var(--spacing-medium) var(--spacing-large); + background: none; + color: var(--header-foreground); + border-bottom: none; +} + +@media screen and (max-width: 767px) { + #titlearea { + padding-bottom: var(--spacing-small); + } +} + +#titlearea table tbody tr { + height: auto !important; +} + +#projectname { + font-size: var(--title-font-size); + font-weight: 600; +} + +#projectnumber { + font-family: inherit; + font-size: 60%; +} + +#projectbrief { + font-family: inherit; + font-size: 80%; +} + +#projectlogo { + vertical-align: middle; +} + +#projectlogo img { + max-height: calc(var(--title-font-size) * 2); + margin-right: var(--spacing-small); +} + +.sm-dox, .tabs, .tabs2, .tabs3 { + background: none; + padding: 0; +} + +.tabs, .tabs2, .tabs3 { + border-bottom: 1px solid var(--separator-color); + margin-bottom: -1px; +} + +.main-menu-btn-icon, .main-menu-btn-icon:before, .main-menu-btn-icon:after { + background: var(--page-secondary-foreground-color); +} + +@media screen and (max-width: 767px) { + .sm-dox a span.sub-arrow { + background: var(--code-background); + } + + #main-menu a.has-submenu span.sub-arrow { + color: var(--page-secondary-foreground-color); + border-radius: var(--border-radius-medium); + } + + #main-menu a.has-submenu:hover span.sub-arrow { + color: var(--page-foreground-color); + } +} + +@media screen and (min-width: 768px) { + .sm-dox li, .tablist li { + display: var(--menu-display); + } + + .sm-dox a span.sub-arrow { + border-color: var(--header-foreground) transparent transparent transparent; + } + + .sm-dox a:hover span.sub-arrow { + border-color: var(--menu-focus-foreground) transparent transparent transparent; + } + + .sm-dox ul a span.sub-arrow { + border-color: transparent transparent transparent var(--page-foreground-color); + } + + .sm-dox ul a:hover span.sub-arrow { + border-color: transparent transparent transparent var(--menu-focus-foreground); + } +} + +.sm-dox ul { + background: var(--page-background-color); + box-shadow: var(--box-shadow); + border: 1px solid var(--separator-color); + border-radius: var(--border-radius-medium) !important; + padding: var(--spacing-small); + animation: ease-out 150ms slideInMenu; +} + +@keyframes slideInMenu { + from { + opacity: 0; + transform: translate(0px, -2px); + } + + to { + opacity: 1; + transform: translate(0px, 0px); + } +} + +.sm-dox ul a { + color: var(--page-foreground-color) !important; + background: var(--page-background-color); + font-size: var(--navigation-font-size); +} + +.sm-dox>li>ul:after { + border-bottom-color: var(--page-background-color) !important; +} + +.sm-dox>li>ul:before { + border-bottom-color: var(--separator-color) !important; +} + +.sm-dox ul a:hover, .sm-dox ul a:active, .sm-dox ul a:focus { + font-size: var(--navigation-font-size) !important; + color: var(--menu-focus-foreground) !important; + text-shadow: none; + background-color: var(--menu-focus-background); + border-radius: var(--border-radius-small) !important; +} + +.sm-dox a, .sm-dox a:focus, .tablist li, .tablist li a, .tablist li.current a { + text-shadow: none; + background: transparent; + background-image: none !important; + color: var(--header-foreground) !important; + font-weight: normal; + font-size: var(--navigation-font-size); + border-radius: var(--border-radius-small) !important; +} + +.sm-dox a:focus { + outline: auto; +} + +.sm-dox a:hover, .sm-dox a:active, .tablist li a:hover { + text-shadow: none; + font-weight: normal; + background: var(--menu-focus-background); + color: var(--menu-focus-foreground) !important; + border-radius: var(--border-radius-small) !important; + font-size: var(--navigation-font-size); +} + +.tablist li.current { + border-radius: var(--border-radius-small); + background: var(--menu-selected-background); +} + +.tablist li { + margin: var(--spacing-small) 0 var(--spacing-small) var(--spacing-small); +} + +.tablist a { + padding: 0 var(--spacing-large); +} + + +/* + Search box + */ + +#MSearchBox { + height: var(--searchbar-height); + background: var(--searchbar-background); + border-radius: var(--searchbar-border-radius); + border: 1px solid var(--separator-color); + overflow: hidden; + width: var(--searchbar-width); + position: relative; + box-shadow: none; + display: block; + margin-top: 0; +} + +/* until Doxygen 1.9.4 */ +.left img#MSearchSelect { + left: 0; + user-select: none; + padding-left: 8px; +} + +/* Doxygen 1.9.5 */ +.left span#MSearchSelect { + left: 0; + user-select: none; + margin-left: 8px; + padding: 0; +} + +.left #MSearchSelect[src$=".png"] { + padding-left: 0 +} + +.SelectionMark { + user-select: none; +} + +.tabs .left #MSearchSelect { + padding-left: 0; +} + +.tabs #MSearchBox { + position: absolute; + right: var(--spacing-medium); +} + +@media screen and (max-width: 767px) { + .tabs #MSearchBox { + position: relative; + right: 0; + margin-left: var(--spacing-medium); + margin-top: 0; + } +} + +#MSearchSelectWindow, #MSearchResultsWindow { + z-index: 9999; +} + +#MSearchBox.MSearchBoxActive { + border-color: var(--primary-color); + box-shadow: inset 0 0 0 1px var(--primary-color); +} + +#main-menu > li:last-child { + margin-right: 0; +} + +@media screen and (max-width: 767px) { + #main-menu > li:last-child { + height: 50px; + } +} + +#MSearchField { + font-size: var(--navigation-font-size); + height: calc(var(--searchbar-height) - 2px); + background: transparent; + width: calc(var(--searchbar-width) - 64px); +} + +.MSearchBoxActive #MSearchField { + color: var(--searchbar-foreground); +} + +#MSearchSelect { + top: calc(calc(var(--searchbar-height) / 2) - 11px); +} + +#MSearchBox span.left, #MSearchBox span.right { + background: none; + background-image: none; +} + +#MSearchBox span.right { + padding-top: calc(calc(var(--searchbar-height) / 2) - 12px); + position: absolute; + right: var(--spacing-small); +} + +.tabs #MSearchBox span.right { + top: calc(calc(var(--searchbar-height) / 2) - 12px); +} + +@keyframes slideInSearchResults { + from { + opacity: 0; + transform: translate(0, 15px); + } + + to { + opacity: 1; + transform: translate(0, 20px); + } +} + +#MSearchResultsWindow { + left: auto !important; + right: var(--spacing-medium); + border-radius: var(--border-radius-large); + border: 1px solid var(--separator-color); + transform: translate(0, 20px); + box-shadow: var(--box-shadow); + animation: ease-out 280ms slideInSearchResults; + background: var(--page-background-color); +} + +iframe#MSearchResults { + margin: 4px; +} + +iframe { + color-scheme: normal; +} + +@media (prefers-color-scheme: dark) { + html:not(.light-mode) iframe#MSearchResults { + filter: invert() hue-rotate(180deg); + } +} + +html.dark-mode iframe#MSearchResults { + filter: invert() hue-rotate(180deg); +} + +#MSearchResults .SRPage { + background-color: transparent; +} + +#MSearchResults .SRPage .SREntry { + font-size: 10pt; + padding: var(--spacing-small) var(--spacing-medium); +} + +#MSearchSelectWindow { + border: 1px solid var(--separator-color); + border-radius: var(--border-radius-medium); + box-shadow: var(--box-shadow); + background: var(--page-background-color); + padding-top: var(--spacing-small); + padding-bottom: var(--spacing-small); +} + +#MSearchSelectWindow a.SelectItem { + font-size: var(--navigation-font-size); + line-height: var(--content-line-height); + margin: 0 var(--spacing-small); + border-radius: var(--border-radius-small); + color: var(--page-foreground-color) !important; + font-weight: normal; +} + +#MSearchSelectWindow a.SelectItem:hover { + background: var(--menu-focus-background); + color: var(--menu-focus-foreground) !important; +} + +@media screen and (max-width: 767px) { + #MSearchBox { + margin-top: var(--spacing-medium); + margin-bottom: var(--spacing-medium); + width: calc(100vw - 30px); + } + + #main-menu > li:last-child { + float: none !important; + } + + #MSearchField { + width: calc(100vw - 110px); + } + + @keyframes slideInSearchResultsMobile { + from { + opacity: 0; + transform: translate(0, 15px); + } + + to { + opacity: 1; + transform: translate(0, 20px); + } + } + + #MSearchResultsWindow { + left: var(--spacing-medium) !important; + right: var(--spacing-medium); + overflow: auto; + transform: translate(0, 20px); + animation: ease-out 280ms slideInSearchResultsMobile; + width: auto !important; + } + + /* + * Overwrites for fixing the searchbox on mobile in doxygen 1.9.2 + */ + label.main-menu-btn ~ #searchBoxPos1 { + top: 3px !important; + right: 6px !important; + left: 45px; + display: flex; + } + + label.main-menu-btn ~ #searchBoxPos1 > #MSearchBox { + margin-top: 0; + margin-bottom: 0; + flex-grow: 2; + float: left; + } +} + +/* + Tree view + */ + +#side-nav { + padding: 0 !important; + background: var(--side-nav-background); + min-width: 8px; + max-width: 50vw; +} + +@media screen and (max-width: 767px) { + #side-nav { + display: none; + } + + #doc-content { + margin-left: 0 !important; + } +} + +#nav-tree { + background: transparent; + margin-right: 1px; +} + +#nav-tree .label { + font-size: var(--navigation-font-size); +} + +#nav-tree .item { + height: var(--tree-item-height); + line-height: var(--tree-item-height); +} + +#nav-tree .item > a:focus { + outline: none; +} + +#nav-sync { + bottom: 12px; + right: 12px; + top: auto !important; + user-select: none; +} + +#nav-tree .selected { + text-shadow: none; + background-image: none; + background-color: transparent; + position: relative; +} + +#nav-tree .selected::after { + content: ""; + position: absolute; + top: 1px; + bottom: 1px; + left: 0; + width: 4px; + border-radius: 0 var(--border-radius-small) var(--border-radius-small) 0; + background: var(--primary-color); +} + + +#nav-tree a { + color: var(--side-nav-foreground) !important; + font-weight: normal; +} + +#nav-tree a:focus { + outline-style: auto; +} + +#nav-tree .arrow { + opacity: var(--side-nav-arrow-opacity); + background: none; +} + +.arrow { + color: inherit; + cursor: pointer; + font-size: 45%; + vertical-align: middle; + margin-right: 2px; + font-family: serif; + height: auto; + text-align: right; +} + +#nav-tree div.item:hover .arrow, #nav-tree a:focus .arrow { + opacity: var(--side-nav-arrow-hover-opacity); +} + +#nav-tree .selected a { + color: var(--primary-color) !important; + font-weight: bolder; + font-weight: 600; +} + +.ui-resizable-e { + width: 4px; + background: transparent; + box-shadow: inset -1px 0 0 0 var(--separator-color); +} + +/* + Contents + */ + +div.header { + border-bottom: 1px solid var(--separator-color); + background-color: var(--page-background-color); + background-image: none; +} + +@media screen and (min-width: 1000px) { + #doc-content > div > div.contents, + .PageDoc > div.contents { + display: flex; + flex-direction: row-reverse; + flex-wrap: nowrap; + align-items: flex-start; + } + + div.contents .textblock { + min-width: 200px; + flex-grow: 1; + } +} + +div.contents, div.header .title, div.header .summary { + max-width: var(--content-maxwidth); +} + +div.contents, div.header .title { + line-height: initial; + margin: calc(var(--spacing-medium) + .2em) auto var(--spacing-medium) auto; +} + +div.header .summary { + margin: var(--spacing-medium) auto 0 auto; +} + +div.headertitle { + padding: 0; +} + +div.header .title { + font-weight: 600; + font-size: 225%; + padding: var(--spacing-medium) var(--spacing-large); + word-break: break-word; +} + +div.header .summary { + width: auto; + display: block; + float: none; + padding: 0 var(--spacing-large); +} + +td.memSeparator { + border-color: var(--separator-color); +} + +span.mlabel { + background: var(--primary-color); + border: none; + padding: 4px 9px; + border-radius: 12px; + margin-right: var(--spacing-medium); +} + +span.mlabel:last-of-type { + margin-right: 2px; +} + +div.contents { + padding: 0 var(--spacing-large); +} + +div.contents p, div.contents li { + line-height: var(--content-line-height); +} + +div.contents div.dyncontent { + margin: var(--spacing-medium) 0; +} + +@media (prefers-color-scheme: dark) { + html:not(.light-mode) div.contents div.dyncontent img, + html:not(.light-mode) div.contents center img, + html:not(.light-mode) div.contents > table img, + html:not(.light-mode) div.contents div.dyncontent iframe, + html:not(.light-mode) div.contents center iframe, + html:not(.light-mode) div.contents table iframe, + html:not(.light-mode) div.contents .dotgraph iframe { + filter: brightness(89%) hue-rotate(180deg) invert(); + } +} + +html.dark-mode div.contents div.dyncontent img, +html.dark-mode div.contents center img, +html.dark-mode div.contents > table img, +html.dark-mode div.contents div.dyncontent iframe, +html.dark-mode div.contents center iframe, +html.dark-mode div.contents table iframe, +html.dark-mode div.contents .dotgraph iframe + { + filter: brightness(89%) hue-rotate(180deg) invert(); +} + +h2.groupheader { + border-bottom: 0px; + color: var(--page-foreground-color); + box-shadow: + 100px 0 var(--page-background-color), + -100px 0 var(--page-background-color), + 100px 0.75px var(--separator-color), + -100px 0.75px var(--separator-color), + 500px 0 var(--page-background-color), + -500px 0 var(--page-background-color), + 500px 0.75px var(--separator-color), + -500px 0.75px var(--separator-color), + 900px 0 var(--page-background-color), + -900px 0 var(--page-background-color), + 900px 0.75px var(--separator-color), + -900px 0.75px var(--separator-color), + 1400px 0 var(--page-background-color), + -1400px 0 var(--page-background-color), + 1400px 0.75px var(--separator-color), + -1400px 0.75px var(--separator-color), + 1900px 0 var(--page-background-color), + -1900px 0 var(--page-background-color), + 1900px 0.75px var(--separator-color), + -1900px 0.75px var(--separator-color); +} + +blockquote { + margin: 0 var(--spacing-medium) 0 var(--spacing-medium); + padding: var(--spacing-small) var(--spacing-large); + background: var(--blockquote-background); + color: var(--blockquote-foreground); + border-left: 0; + overflow: visible; + border-radius: var(--border-radius-medium); + overflow: visible; + position: relative; +} + +blockquote::before, blockquote::after { + font-weight: bold; + font-family: serif; + font-size: 360%; + opacity: .15; + position: absolute; +} + +blockquote::before { + content: "“"; + left: -10px; + top: 4px; +} + +blockquote::after { + content: "”"; + right: -8px; + bottom: -25px; +} + +blockquote p { + margin: var(--spacing-small) 0 var(--spacing-medium) 0; +} +.paramname, .paramname em { + font-weight: 600; + color: var(--primary-dark-color); +} + +.paramname > code { + border: 0; +} + +table.params .paramname { + font-weight: 600; + font-family: var(--font-family-monospace); + font-size: var(--code-font-size); + padding-right: var(--spacing-small); + line-height: var(--table-line-height); +} + +h1.glow, h2.glow, h3.glow, h4.glow, h5.glow, h6.glow { + text-shadow: 0 0 15px var(--primary-light-color); +} + +.alphachar a { + color: var(--page-foreground-color); +} + +.dotgraph { + max-width: 100%; + overflow-x: scroll; +} + +.dotgraph .caption { + position: sticky; + left: 0; +} + +/* Wrap Graphviz graphs with the `interactive_dotgraph` class if `INTERACTIVE_SVG = YES` */ +.interactive_dotgraph .dotgraph iframe { + max-width: 100%; +} + +/* + Table of Contents + */ + +div.contents .toc { + max-height: var(--toc-max-height); + min-width: var(--toc-width); + border: 0; + border-left: 1px solid var(--separator-color); + border-radius: 0; + background-color: var(--page-background-color); + box-shadow: none; + position: sticky; + top: var(--toc-sticky-top); + padding: 0 var(--spacing-large); + margin: var(--spacing-small) 0 var(--spacing-large) var(--spacing-large); +} + +div.toc h3 { + color: var(--toc-foreground); + font-size: var(--navigation-font-size); + margin: var(--spacing-large) 0 var(--spacing-medium) 0; +} + +div.toc li { + padding: 0; + background: none; + line-height: var(--toc-font-size); + margin: var(--toc-font-size) 0 0 0; +} + +div.toc li::before { + display: none; +} + +div.toc ul { + margin-top: 0 +} + +div.toc li a { + font-size: var(--toc-font-size); + color: var(--page-foreground-color) !important; + text-decoration: none; +} + +div.toc li a:hover, div.toc li a.active { + color: var(--primary-color) !important; +} + +div.toc li a.aboveActive { + color: var(--page-secondary-foreground-color) !important; +} + + +@media screen and (max-width: 999px) { + div.contents .toc { + max-height: 45vh; + float: none; + width: auto; + margin: 0 0 var(--spacing-medium) 0; + position: relative; + top: 0; + position: relative; + border: 1px solid var(--separator-color); + border-radius: var(--border-radius-medium); + background-color: var(--toc-background); + box-shadow: var(--box-shadow); + } + + div.contents .toc.interactive { + max-height: calc(var(--navigation-font-size) + 2 * var(--spacing-large)); + overflow: hidden; + } + + div.contents .toc > h3 { + -webkit-tap-highlight-color: transparent; + cursor: pointer; + position: sticky; + top: 0; + background-color: var(--toc-background); + margin: 0; + padding: var(--spacing-large) 0; + display: block; + } + + div.contents .toc.interactive > h3::before { + content: ""; + width: 0; + height: 0; + border-left: 4px solid transparent; + border-right: 4px solid transparent; + border-top: 5px solid var(--primary-color); + display: inline-block; + margin-right: var(--spacing-small); + margin-bottom: calc(var(--navigation-font-size) / 4); + transform: rotate(-90deg); + transition: transform var(--animation-duration) ease-out; + } + + div.contents .toc.interactive.open > h3::before { + transform: rotate(0deg); + } + + div.contents .toc.interactive.open { + max-height: 45vh; + overflow: auto; + transition: max-height 0.2s ease-in-out; + } + + div.contents .toc a, div.contents .toc a.active { + color: var(--primary-color) !important; + } + + div.contents .toc a:hover { + text-decoration: underline; + } +} + +/* + Code & Fragments + */ + +code, div.fragment, pre.fragment { + border-radius: var(--border-radius-small); + border: 1px solid var(--separator-color); + overflow: hidden; +} + +code { + display: inline; + background: var(--code-background); + color: var(--code-foreground); + padding: 2px 6px; +} + +div.fragment, pre.fragment { + margin: var(--spacing-medium) 0; + padding: calc(var(--spacing-large) - (var(--spacing-large) / 6)) var(--spacing-large); + background: var(--fragment-background); + color: var(--fragment-foreground); + overflow-x: auto; +} + +@media screen and (max-width: 767px) { + div.fragment, pre.fragment { + border-top-right-radius: 0; + border-bottom-right-radius: 0; + border-right: 0; + } + + .contents > div.fragment, + .textblock > div.fragment, + .textblock > pre.fragment, + .textblock > .tabbed > ul > li > div.fragment, + .textblock > .tabbed > ul > li > pre.fragment, + .contents > .doxygen-awesome-fragment-wrapper > div.fragment, + .textblock > .doxygen-awesome-fragment-wrapper > div.fragment, + .textblock > .doxygen-awesome-fragment-wrapper > pre.fragment, + .textblock > .tabbed > ul > li > .doxygen-awesome-fragment-wrapper > div.fragment, + .textblock > .tabbed > ul > li > .doxygen-awesome-fragment-wrapper > pre.fragment { + margin: var(--spacing-medium) calc(0px - var(--spacing-large)); + border-radius: 0; + border-left: 0; + } + + .textblock li > .fragment, + .textblock li > .doxygen-awesome-fragment-wrapper > .fragment { + margin: var(--spacing-medium) calc(0px - var(--spacing-large)); + } + + .memdoc li > .fragment, + .memdoc li > .doxygen-awesome-fragment-wrapper > .fragment { + margin: var(--spacing-medium) calc(0px - var(--spacing-medium)); + } + + .textblock ul, .memdoc ul { + overflow: initial; + } + + .memdoc > div.fragment, + .memdoc > pre.fragment, + dl dd > div.fragment, + dl dd pre.fragment, + .memdoc > .doxygen-awesome-fragment-wrapper > div.fragment, + .memdoc > .doxygen-awesome-fragment-wrapper > pre.fragment, + dl dd > .doxygen-awesome-fragment-wrapper > div.fragment, + dl dd .doxygen-awesome-fragment-wrapper > pre.fragment { + margin: var(--spacing-medium) calc(0px - var(--spacing-medium)); + border-radius: 0; + border-left: 0; + } +} + +code, code a, pre.fragment, div.fragment, div.fragment .line, div.fragment span, div.fragment .line a, div.fragment .line span { + font-family: var(--font-family-monospace); + font-size: var(--code-font-size) !important; +} + +div.line:after { + margin-right: var(--spacing-medium); +} + +div.fragment .line, pre.fragment { + white-space: pre; + word-wrap: initial; + line-height: var(--fragment-lineheight); +} + +div.fragment span.keyword { + color: var(--fragment-keyword); +} + +div.fragment span.keywordtype { + color: var(--fragment-keywordtype); +} + +div.fragment span.keywordflow { + color: var(--fragment-keywordflow); +} + +div.fragment span.stringliteral { + color: var(--fragment-token) +} + +div.fragment span.comment { + color: var(--fragment-comment); +} + +div.fragment a.code { + color: var(--fragment-link) !important; +} + +div.fragment span.preprocessor { + color: var(--fragment-preprocessor); +} + +div.fragment span.lineno { + display: inline-block; + width: 27px; + border-right: none; + background: var(--fragment-linenumber-background); + color: var(--fragment-linenumber-color); +} + +div.fragment span.lineno a { + background: none; + color: var(--fragment-link) !important; +} + +div.fragment > .line:first-child .lineno { + box-shadow: -999999px 0px 0 999999px var(--fragment-linenumber-background), -999998px 0px 0 999999px var(--fragment-linenumber-border); + background-color: var(--fragment-linenumber-background) !important; +} + +div.line { + border-radius: var(--border-radius-small); +} + +div.line.glow { + background-color: var(--primary-light-color); + box-shadow: none; +} + +/* + dl warning, attention, note, deprecated, bug, ... + */ + +dl.bug dt a, dl.deprecated dt a, dl.todo dt a { + font-weight: bold !important; +} + +dl.warning, dl.attention, dl.note, dl.deprecated, dl.bug, dl.invariant, dl.pre, dl.post, dl.todo, dl.remark { + padding: var(--spacing-medium); + margin: var(--spacing-medium) 0; + color: var(--page-background-color); + overflow: hidden; + margin-left: 0; + border-radius: var(--border-radius-small); +} + +dl.section dd { + margin-bottom: 2px; +} + +dl.warning, dl.attention { + background: var(--warning-color); + border-left: 8px solid var(--warning-color-dark); + color: var(--warning-color-darker); +} + +dl.warning dt, dl.attention dt { + color: var(--warning-color-dark); +} + +dl.note, dl.remark { + background: var(--note-color); + border-left: 8px solid var(--note-color-dark); + color: var(--note-color-darker); +} + +dl.note dt, dl.remark dt { + color: var(--note-color-dark); +} + +dl.todo { + background: var(--todo-color); + border-left: 8px solid var(--todo-color-dark); + color: var(--todo-color-darker); +} + +dl.todo dt a { + color: var(--todo-color-dark) !important; +} + +dl.bug dt a { + color: var(--todo-color-dark) !important; +} + +dl.bug { + background: var(--bug-color); + border-left: 8px solid var(--bug-color-dark); + color: var(--bug-color-darker); +} + +dl.bug dt a { + color: var(--bug-color-dark) !important; +} + +dl.deprecated { + background: var(--deprecated-color); + border-left: 8px solid var(--deprecated-color-dark); + color: var(--deprecated-color-darker); +} + +dl.deprecated dt a { + color: var(--deprecated-color-dark) !important; +} + +dl.section dd, dl.bug dd, dl.deprecated dd, dl.todo dd { + margin-inline-start: 0px; +} + +dl.invariant, dl.pre, dl.post { + background: var(--invariant-color); + border-left: 8px solid var(--invariant-color-dark); + color: var(--invariant-color-darker); +} + +dl.invariant dt, dl.pre dt, dl.post dt { + color: var(--invariant-color-dark); +} + +/* + memitem + */ + +div.memdoc, div.memproto, h2.memtitle { + box-shadow: none; + background-image: none; + border: none; +} + +div.memdoc { + padding: 0 var(--spacing-medium); + background: var(--page-background-color); +} + +h2.memtitle, div.memitem { + border: 1px solid var(--separator-color); + box-shadow: var(--box-shadow); +} + +h2.memtitle { + box-shadow: 0px var(--spacing-medium) 0 -1px var(--fragment-background), var(--box-shadow); +} + +div.memitem { + transition: none; +} + +div.memproto, h2.memtitle { + background: var(--fragment-background); +} + +h2.memtitle { + font-weight: 500; + font-size: var(--memtitle-font-size); + font-family: var(--font-family-monospace); + border-bottom: none; + border-top-left-radius: var(--border-radius-medium); + border-top-right-radius: var(--border-radius-medium); + word-break: break-all; + position: relative; +} + +h2.memtitle:after { + content: ""; + display: block; + background: var(--fragment-background); + height: var(--spacing-medium); + bottom: calc(0px - var(--spacing-medium)); + left: 0; + right: -14px; + position: absolute; + border-top-right-radius: var(--border-radius-medium); +} + +h2.memtitle > span.permalink { + font-size: inherit; +} + +h2.memtitle > span.permalink > a { + text-decoration: none; + padding-left: 3px; + margin-right: -4px; + user-select: none; + display: inline-block; + margin-top: -6px; +} + +h2.memtitle > span.permalink > a:hover { + color: var(--primary-dark-color) !important; +} + +a:target + h2.memtitle, a:target + h2.memtitle + div.memitem { + border-color: var(--primary-light-color); +} + +div.memitem { + border-top-right-radius: var(--border-radius-medium); + border-bottom-right-radius: var(--border-radius-medium); + border-bottom-left-radius: var(--border-radius-medium); + overflow: hidden; + display: block !important; +} + +div.memdoc { + border-radius: 0; +} + +div.memproto { + border-radius: 0 var(--border-radius-small) 0 0; + overflow: auto; + border-bottom: 1px solid var(--separator-color); + padding: var(--spacing-medium); + margin-bottom: -1px; +} + +div.memtitle { + border-top-right-radius: var(--border-radius-medium); + border-top-left-radius: var(--border-radius-medium); +} + +div.memproto table.memname { + font-family: var(--font-family-monospace); + color: var(--page-foreground-color); + font-size: var(--memname-font-size); + text-shadow: none; +} + +div.memproto div.memtemplate { + font-family: var(--font-family-monospace); + color: var(--primary-dark-color); + font-size: var(--memname-font-size); + margin-left: 2px; + text-shadow: none; +} + +table.mlabels, table.mlabels > tbody { + display: block; +} + +td.mlabels-left { + width: auto; +} + +td.mlabels-right { + margin-top: 3px; + position: sticky; + left: 0; +} + +table.mlabels > tbody > tr:first-child { + display: flex; + justify-content: space-between; + flex-wrap: wrap; +} + +.memname, .memitem span.mlabels { + margin: 0 +} + +/* + reflist + */ + +dl.reflist { + box-shadow: var(--box-shadow); + border-radius: var(--border-radius-medium); + border: 1px solid var(--separator-color); + overflow: hidden; + padding: 0; +} + + +dl.reflist dt, dl.reflist dd { + box-shadow: none; + text-shadow: none; + background-image: none; + border: none; + padding: 12px; +} + + +dl.reflist dt { + font-weight: 500; + border-radius: 0; + background: var(--code-background); + border-bottom: 1px solid var(--separator-color); + color: var(--page-foreground-color) +} + + +dl.reflist dd { + background: none; +} + +/* + Table + */ + +.contents table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname), +.contents table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname) tbody { + display: inline-block; + max-width: 100%; +} + +.contents > table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname):not(.classindex) { + margin-left: calc(0px - var(--spacing-large)); + margin-right: calc(0px - var(--spacing-large)); + max-width: calc(100% + 2 * var(--spacing-large)); +} + +table.fieldtable, +table.markdownTable tbody, +table.doxtable tbody { + border: none; + margin: var(--spacing-medium) 0; + box-shadow: 0 0 0 1px var(--separator-color); + border-radius: var(--border-radius-small); +} + +table.markdownTable, table.doxtable, table.fieldtable { + padding: 1px; +} + +table.doxtable caption { + display: block; +} + +table.fieldtable { + border-collapse: collapse; + width: 100%; +} + +th.markdownTableHeadLeft, +th.markdownTableHeadRight, +th.markdownTableHeadCenter, +th.markdownTableHeadNone, +table.doxtable th { + background: var(--tablehead-background); + color: var(--tablehead-foreground); + font-weight: 600; + font-size: var(--page-font-size); +} + +th.markdownTableHeadLeft:first-child, +th.markdownTableHeadRight:first-child, +th.markdownTableHeadCenter:first-child, +th.markdownTableHeadNone:first-child, +table.doxtable tr th:first-child { + border-top-left-radius: var(--border-radius-small); +} + +th.markdownTableHeadLeft:last-child, +th.markdownTableHeadRight:last-child, +th.markdownTableHeadCenter:last-child, +th.markdownTableHeadNone:last-child, +table.doxtable tr th:last-child { + border-top-right-radius: var(--border-radius-small); +} + +table.markdownTable td, +table.markdownTable th, +table.fieldtable td, +table.fieldtable th, +table.doxtable td, +table.doxtable th { + border: 1px solid var(--separator-color); + padding: var(--spacing-small) var(--spacing-medium); +} + +table.markdownTable td:last-child, +table.markdownTable th:last-child, +table.fieldtable td:last-child, +table.fieldtable th:last-child, +table.doxtable td:last-child, +table.doxtable th:last-child { + border-right: none; +} + +table.markdownTable td:first-child, +table.markdownTable th:first-child, +table.fieldtable td:first-child, +table.fieldtable th:first-child, +table.doxtable td:first-child, +table.doxtable th:first-child { + border-left: none; +} + +table.markdownTable tr:first-child td, +table.markdownTable tr:first-child th, +table.fieldtable tr:first-child td, +table.fieldtable tr:first-child th, +table.doxtable tr:first-child td, +table.doxtable tr:first-child th { + border-top: none; +} + +table.markdownTable tr:last-child td, +table.markdownTable tr:last-child th, +table.fieldtable tr:last-child td, +table.fieldtable tr:last-child th, +table.doxtable tr:last-child td, +table.doxtable tr:last-child th { + border-bottom: none; +} + +table.markdownTable tr, table.doxtable tr { + border-bottom: 1px solid var(--separator-color); +} + +table.markdownTable tr:last-child, table.doxtable tr:last-child { + border-bottom: none; +} + +.full_width_table table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname) { + display: block; +} + +.full_width_table table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname) tbody { + display: table; + width: 100%; +} + +table.fieldtable th { + font-size: var(--page-font-size); + font-weight: 600; + background-image: none; + background-color: var(--tablehead-background); + color: var(--tablehead-foreground); +} + +table.fieldtable td.fieldtype, .fieldtable td.fieldname, .fieldtable td.fielddoc, .fieldtable th { + border-bottom: 1px solid var(--separator-color); + border-right: 1px solid var(--separator-color); +} + +table.fieldtable tr:last-child td:first-child { + border-bottom-left-radius: var(--border-radius-small); +} + +table.fieldtable tr:last-child td:last-child { + border-bottom-right-radius: var(--border-radius-small); +} + +.memberdecls td.glow, .fieldtable tr.glow { + background-color: var(--primary-light-color); + box-shadow: none; +} + +table.memberdecls { + display: block; + -webkit-tap-highlight-color: transparent; +} + +table.memberdecls tr[class^='memitem'] { + font-family: var(--font-family-monospace); + font-size: var(--code-font-size); +} + +table.memberdecls tr[class^='memitem'] .memTemplParams { + font-family: var(--font-family-monospace); + font-size: var(--code-font-size); + color: var(--primary-dark-color); + white-space: normal; +} + +table.memberdecls .memItemLeft, +table.memberdecls .memItemRight, +table.memberdecls .memTemplItemLeft, +table.memberdecls .memTemplItemRight, +table.memberdecls .memTemplParams { + transition: none; + padding-top: var(--spacing-small); + padding-bottom: var(--spacing-small); + border-top: 1px solid var(--separator-color); + border-bottom: 1px solid var(--separator-color); + background-color: var(--fragment-background); +} + +table.memberdecls .memTemplItemLeft, +table.memberdecls .memTemplItemRight { + padding-top: 2px; +} + +table.memberdecls .memTemplParams { + border-bottom: 0; + border-left: 1px solid var(--separator-color); + border-right: 1px solid var(--separator-color); + border-radius: var(--border-radius-small) var(--border-radius-small) 0 0; + padding-bottom: var(--spacing-small); +} + +table.memberdecls .memTemplItemLeft { + border-radius: 0 0 0 var(--border-radius-small); + border-left: 1px solid var(--separator-color); + border-top: 0; +} + +table.memberdecls .memTemplItemRight { + border-radius: 0 0 var(--border-radius-small) 0; + border-right: 1px solid var(--separator-color); + padding-left: 0; + border-top: 0; +} + +table.memberdecls .memItemLeft { + border-radius: var(--border-radius-small) 0 0 var(--border-radius-small); + border-left: 1px solid var(--separator-color); + padding-left: var(--spacing-medium); + padding-right: 0; +} + +table.memberdecls .memItemRight { + border-radius: 0 var(--border-radius-small) var(--border-radius-small) 0; + border-right: 1px solid var(--separator-color); + padding-right: var(--spacing-medium); + padding-left: 0; + +} + +table.memberdecls .mdescLeft, table.memberdecls .mdescRight { + background: none; + color: var(--page-foreground-color); + padding: var(--spacing-small) 0; +} + +table.memberdecls .memItemLeft, +table.memberdecls .memTemplItemLeft { + padding-right: var(--spacing-medium); +} + +table.memberdecls .memSeparator { + background: var(--page-background-color); + height: var(--spacing-large); + border: 0; + transition: none; +} + +table.memberdecls .groupheader { + margin-bottom: var(--spacing-large); +} + +table.memberdecls .inherit_header td { + padding: 0 0 var(--spacing-medium) 0; + text-indent: -12px; + color: var(--page-secondary-foreground-color); +} + +table.memberdecls img[src="closed.png"], +table.memberdecls img[src="open.png"], +div.dynheader img[src="open.png"], +div.dynheader img[src="closed.png"] { + width: 0; + height: 0; + border-left: 4px solid transparent; + border-right: 4px solid transparent; + border-top: 5px solid var(--primary-color); + margin-top: 8px; + display: block; + float: left; + margin-left: -10px; + transition: transform var(--animation-duration) ease-out; +} + +table.memberdecls img { + margin-right: 10px; +} + +table.memberdecls img[src="closed.png"], +div.dynheader img[src="closed.png"] { + transform: rotate(-90deg); + +} + +.compoundTemplParams { + font-family: var(--font-family-monospace); + color: var(--primary-dark-color); + font-size: var(--code-font-size); +} + +@media screen and (max-width: 767px) { + + table.memberdecls .memItemLeft, + table.memberdecls .memItemRight, + table.memberdecls .mdescLeft, + table.memberdecls .mdescRight, + table.memberdecls .memTemplItemLeft, + table.memberdecls .memTemplItemRight, + table.memberdecls .memTemplParams { + display: block; + text-align: left; + padding-left: var(--spacing-large); + margin: 0 calc(0px - var(--spacing-large)) 0 calc(0px - var(--spacing-large)); + border-right: none; + border-left: none; + border-radius: 0; + white-space: normal; + } + + table.memberdecls .memItemLeft, + table.memberdecls .mdescLeft, + table.memberdecls .memTemplItemLeft { + border-bottom: 0; + padding-bottom: 0; + } + + table.memberdecls .memTemplItemLeft { + padding-top: 0; + } + + table.memberdecls .mdescLeft { + margin-bottom: calc(0px - var(--page-font-size)); + } + + table.memberdecls .memItemRight, + table.memberdecls .mdescRight, + table.memberdecls .memTemplItemRight { + border-top: 0; + padding-top: 0; + padding-right: var(--spacing-large); + overflow-x: auto; + } + + table.memberdecls tr[class^='memitem']:not(.inherit) { + display: block; + width: calc(100vw - 2 * var(--spacing-large)); + } + + table.memberdecls .mdescRight { + color: var(--page-foreground-color); + } + + table.memberdecls tr.inherit { + visibility: hidden; + } + + table.memberdecls tr[style="display: table-row;"] { + display: block !important; + visibility: visible; + width: calc(100vw - 2 * var(--spacing-large)); + animation: fade .5s; + } + + @keyframes fade { + 0% { + opacity: 0; + max-height: 0; + } + + 100% { + opacity: 1; + max-height: 200px; + } + } +} + + +/* + Horizontal Rule + */ + +hr { + margin-top: var(--spacing-large); + margin-bottom: var(--spacing-large); + height: 1px; + background-color: var(--separator-color); + border: 0; +} + +.contents hr { + box-shadow: 100px 0 var(--separator-color), + -100px 0 var(--separator-color), + 500px 0 var(--separator-color), + -500px 0 var(--separator-color), + 900px 0 var(--separator-color), + -900px 0 var(--separator-color), + 1400px 0 var(--separator-color), + -1400px 0 var(--separator-color), + 1900px 0 var(--separator-color), + -1900px 0 var(--separator-color); +} + +.contents img, .contents .center, .contents center, .contents div.image object { + max-width: 100%; + overflow: auto; +} + +@media screen and (max-width: 767px) { + .contents .dyncontent > .center, .contents > center { + margin-left: calc(0px - var(--spacing-large)); + margin-right: calc(0px - var(--spacing-large)); + max-width: calc(100% + 2 * var(--spacing-large)); + } +} + +/* + Directories + */ +div.directory { + border-top: 1px solid var(--separator-color); + border-bottom: 1px solid var(--separator-color); + width: auto; +} + +table.directory { + font-family: var(--font-family); + font-size: var(--page-font-size); + font-weight: normal; + width: 100%; +} + +table.directory td.entry, table.directory td.desc { + padding: calc(var(--spacing-small) / 2) var(--spacing-small); + line-height: var(--table-line-height); +} + +table.directory tr.even td:last-child { + border-radius: 0 var(--border-radius-small) var(--border-radius-small) 0; +} + +table.directory tr.even td:first-child { + border-radius: var(--border-radius-small) 0 0 var(--border-radius-small); +} + +table.directory tr.even:last-child td:last-child { + border-radius: 0 var(--border-radius-small) 0 0; +} + +table.directory tr.even:last-child td:first-child { + border-radius: var(--border-radius-small) 0 0 0; +} + +table.directory td.desc { + min-width: 250px; +} + +table.directory tr.even { + background-color: var(--odd-color); +} + +table.directory tr.odd { + background-color: transparent; +} + +.icona { + width: auto; + height: auto; + margin: 0 var(--spacing-small); +} + +.icon { + background: var(--primary-color); + border-radius: var(--border-radius-small); + font-size: var(--page-font-size); + padding: calc(var(--page-font-size) / 5); + line-height: var(--page-font-size); + transform: scale(0.8); + height: auto; + width: var(--page-font-size); + user-select: none; +} + +.iconfopen, .icondoc, .iconfclosed { + background-position: center; + margin-bottom: 0; + height: var(--table-line-height); +} + +.icondoc { + filter: saturate(0.2); +} + +@media screen and (max-width: 767px) { + div.directory { + margin-left: calc(0px - var(--spacing-large)); + margin-right: calc(0px - var(--spacing-large)); + } +} + +@media (prefers-color-scheme: dark) { + html:not(.light-mode) .iconfopen, html:not(.light-mode) .iconfclosed { + filter: hue-rotate(180deg) invert(); + } +} + +html.dark-mode .iconfopen, html.dark-mode .iconfclosed { + filter: hue-rotate(180deg) invert(); +} + +/* + Class list + */ + +.classindex dl.odd { + background: var(--odd-color); + border-radius: var(--border-radius-small); +} + +.classindex dl.even { + background-color: transparent; +} + +/* + Class Index Doxygen 1.8 +*/ + +table.classindex { + margin-left: 0; + margin-right: 0; + width: 100%; +} + +table.classindex table div.ah { + background-image: none; + background-color: initial; + border-color: var(--separator-color); + color: var(--page-foreground-color); + box-shadow: var(--box-shadow); + border-radius: var(--border-radius-large); + padding: var(--spacing-small); +} + +div.qindex { + background-color: var(--odd-color); + border-radius: var(--border-radius-small); + border: 1px solid var(--separator-color); + padding: var(--spacing-small) 0; +} + +/* + Footer and nav-path + */ + +#nav-path { + width: 100%; +} + +#nav-path ul { + background-image: none; + background: var(--page-background-color); + border: none; + border-top: 1px solid var(--separator-color); + border-bottom: 1px solid var(--separator-color); + border-bottom: 0; + box-shadow: 0 0.75px 0 var(--separator-color); + font-size: var(--navigation-font-size); +} + +img.footer { + width: 60px; +} + +.navpath li.footer { + color: var(--page-secondary-foreground-color); +} + +address.footer { + color: var(--page-secondary-foreground-color); + margin-bottom: var(--spacing-large); +} + +#nav-path li.navelem { + background-image: none; + display: flex; + align-items: center; +} + +.navpath li.navelem a { + text-shadow: none; + display: inline-block; + color: var(--primary-color) !important; +} + +.navpath li.navelem b { + color: var(--primary-dark-color); + font-weight: 500; +} + +li.navelem { + padding: 0; + margin-left: -8px; +} + +li.navelem:first-child { + margin-left: var(--spacing-large); +} + +li.navelem:first-child:before { + display: none; +} + +#nav-path li.navelem:after { + content: ''; + border: 5px solid var(--page-background-color); + border-bottom-color: transparent; + border-right-color: transparent; + border-top-color: transparent; + transform: translateY(-1px) scaleY(4.2); + z-index: 10; + margin-left: 6px; +} + +#nav-path li.navelem:before { + content: ''; + border: 5px solid var(--separator-color); + border-bottom-color: transparent; + border-right-color: transparent; + border-top-color: transparent; + transform: translateY(-1px) scaleY(3.2); + margin-right: var(--spacing-small); +} + +.navpath li.navelem a:hover { + color: var(--primary-color); +} + +/* + Scrollbars for Webkit +*/ + +#nav-tree::-webkit-scrollbar, +div.fragment::-webkit-scrollbar, +pre.fragment::-webkit-scrollbar, +div.memproto::-webkit-scrollbar, +.contents center::-webkit-scrollbar, +.contents .center::-webkit-scrollbar, +.contents table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname) tbody::-webkit-scrollbar, +div.contents .toc::-webkit-scrollbar, +.contents .dotgraph::-webkit-scrollbar, +.contents .tabs-overview-container::-webkit-scrollbar { + background: transparent; + width: calc(var(--webkit-scrollbar-size) + var(--webkit-scrollbar-padding) + var(--webkit-scrollbar-padding)); + height: calc(var(--webkit-scrollbar-size) + var(--webkit-scrollbar-padding) + var(--webkit-scrollbar-padding)); +} + +#nav-tree::-webkit-scrollbar-thumb, +div.fragment::-webkit-scrollbar-thumb, +pre.fragment::-webkit-scrollbar-thumb, +div.memproto::-webkit-scrollbar-thumb, +.contents center::-webkit-scrollbar-thumb, +.contents .center::-webkit-scrollbar-thumb, +.contents table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname) tbody::-webkit-scrollbar-thumb, +div.contents .toc::-webkit-scrollbar-thumb, +.contents .dotgraph::-webkit-scrollbar-thumb, +.contents .tabs-overview-container::-webkit-scrollbar-thumb { + background-color: transparent; + border: var(--webkit-scrollbar-padding) solid transparent; + border-radius: calc(var(--webkit-scrollbar-padding) + var(--webkit-scrollbar-padding)); + background-clip: padding-box; +} + +#nav-tree:hover::-webkit-scrollbar-thumb, +div.fragment:hover::-webkit-scrollbar-thumb, +pre.fragment:hover::-webkit-scrollbar-thumb, +div.memproto:hover::-webkit-scrollbar-thumb, +.contents center:hover::-webkit-scrollbar-thumb, +.contents .center:hover::-webkit-scrollbar-thumb, +.contents table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname) tbody:hover::-webkit-scrollbar-thumb, +div.contents .toc:hover::-webkit-scrollbar-thumb, +.contents .dotgraph:hover::-webkit-scrollbar-thumb, +.contents .tabs-overview-container:hover::-webkit-scrollbar-thumb { + background-color: var(--webkit-scrollbar-color); +} + +#nav-tree::-webkit-scrollbar-track, +div.fragment::-webkit-scrollbar-track, +pre.fragment::-webkit-scrollbar-track, +div.memproto::-webkit-scrollbar-track, +.contents center::-webkit-scrollbar-track, +.contents .center::-webkit-scrollbar-track, +.contents table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname) tbody::-webkit-scrollbar-track, +div.contents .toc::-webkit-scrollbar-track, +.contents .dotgraph::-webkit-scrollbar-track, +.contents .tabs-overview-container::-webkit-scrollbar-track { + background: transparent; +} + +#nav-tree::-webkit-scrollbar-corner { + background-color: var(--side-nav-background); +} + +#nav-tree, +div.fragment, +pre.fragment, +div.memproto, +.contents center, +.contents .center, +.contents table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname) tbody, +div.contents .toc { + overflow-x: auto; + overflow-x: overlay; +} + +#nav-tree { + overflow-x: auto; + overflow-y: auto; + overflow-y: overlay; +} + +/* + Scrollbars for Firefox +*/ + +#nav-tree, +div.fragment, +pre.fragment, +div.memproto, +.contents center, +.contents .center, +.contents table:not(.memberdecls):not(.mlabels):not(.fieldtable):not(.memname) tbody, +div.contents .toc, +.contents .dotgraph, +.contents .tabs-overview-container { + scrollbar-width: thin; +} + +/* + Optional Dark mode toggle button +*/ + +doxygen-awesome-dark-mode-toggle { + display: inline-block; + margin: 0 0 0 var(--spacing-small); + padding: 0; + width: var(--searchbar-height); + height: var(--searchbar-height); + background: none; + border: none; + border-radius: var(--searchbar-height); + vertical-align: middle; + text-align: center; + line-height: var(--searchbar-height); + font-size: 22px; + display: flex; + align-items: center; + justify-content: center; + user-select: none; + cursor: pointer; +} + +doxygen-awesome-dark-mode-toggle > svg { + transition: transform var(--animation-duration) ease-in-out; +} + +doxygen-awesome-dark-mode-toggle:active > svg { + transform: scale(.5); +} + +doxygen-awesome-dark-mode-toggle:hover { + background-color: rgba(0,0,0,.03); +} + +html.dark-mode doxygen-awesome-dark-mode-toggle:hover { + background-color: rgba(0,0,0,.18); +} + +/* + Optional fragment copy button +*/ +.doxygen-awesome-fragment-wrapper { + position: relative; +} + +doxygen-awesome-fragment-copy-button { + opacity: 0; + background: var(--fragment-background); + width: 28px; + height: 28px; + position: absolute; + right: calc(var(--spacing-large) - (var(--spacing-large) / 2.5)); + top: calc(var(--spacing-large) - (var(--spacing-large) / 2.5)); + border: 1px solid var(--fragment-foreground); + cursor: pointer; + border-radius: var(--border-radius-small); + display: flex; + justify-content: center; + align-items: center; +} + +.doxygen-awesome-fragment-wrapper:hover doxygen-awesome-fragment-copy-button, doxygen-awesome-fragment-copy-button.success { + opacity: .28; +} + +doxygen-awesome-fragment-copy-button:hover, doxygen-awesome-fragment-copy-button.success { + opacity: 1 !important; +} + +doxygen-awesome-fragment-copy-button:active:not([class~=success]) svg { + transform: scale(.91); +} + +doxygen-awesome-fragment-copy-button svg { + fill: var(--fragment-foreground); + width: 18px; + height: 18px; +} + +doxygen-awesome-fragment-copy-button.success svg { + fill: rgb(14, 168, 14); +} + +doxygen-awesome-fragment-copy-button.success { + border-color: rgb(14, 168, 14); +} + +@media screen and (max-width: 767px) { + .textblock > .doxygen-awesome-fragment-wrapper > doxygen-awesome-fragment-copy-button, + .textblock li > .doxygen-awesome-fragment-wrapper > doxygen-awesome-fragment-copy-button, + .memdoc li > .doxygen-awesome-fragment-wrapper > doxygen-awesome-fragment-copy-button, + .memdoc > .doxygen-awesome-fragment-wrapper > doxygen-awesome-fragment-copy-button, + dl dd > .doxygen-awesome-fragment-wrapper > doxygen-awesome-fragment-copy-button { + right: 0; + } +} + +/* + Optional paragraph link button +*/ + +a.anchorlink { + font-size: 90%; + margin-left: var(--spacing-small); + color: var(--page-foreground-color) !important; + text-decoration: none; + opacity: .15; + display: none; + transition: opacity var(--animation-duration) ease-in-out, color var(--animation-duration) ease-in-out; +} + +a.anchorlink svg { + fill: var(--page-foreground-color); +} + +h3 a.anchorlink svg, h4 a.anchorlink svg { + margin-bottom: -3px; + margin-top: -4px; +} + +a.anchorlink:hover { + opacity: .45; +} + +h2:hover a.anchorlink, h1:hover a.anchorlink, h3:hover a.anchorlink, h4:hover a.anchorlink { + display: inline-block; +} + +/* + Optional tab feature +*/ + +.tabbed > ul { + padding-inline-start: 0px; + margin: 0; + padding: var(--spacing-small) 0; +} + +.tabbed > ul > li { + display: none; +} + +.tabbed > ul > li.selected { + display: block; +} + +.tabs-overview-container { + overflow-x: auto; + display: block; + overflow-y: visible; +} + +.tabs-overview { + border-bottom: 1px solid var(--separator-color); + display: flex; + flex-direction: row; +} + +@media screen and (max-width: 767px) { + .tabs-overview-container { + margin: 0 calc(0px - var(--spacing-large)); + } + .tabs-overview { + padding: 0 var(--spacing-large) + } +} + +.tabs-overview button.tab-button { + color: var(--page-foreground-color); + margin: 0; + border: none; + background: transparent; + padding: calc(var(--spacing-large) / 2) 0; + display: inline-block; + font-size: var(--page-font-size); + cursor: pointer; + box-shadow: 0 1px 0 0 var(--separator-color); + position: relative; + + -webkit-tap-highlight-color: transparent; +} + +.tabs-overview button.tab-button .tab-title::before { + display: block; + content: attr(title); + font-weight: 600; + height: 0; + overflow: hidden; + visibility: hidden; +} + +.tabs-overview button.tab-button .tab-title { + float: left; + white-space: nowrap; + font-weight: normal; + padding: calc(var(--spacing-large) / 2) var(--spacing-large); + border-radius: var(--border-radius-medium); + transition: background-color var(--animation-duration) ease-in-out, font-weight var(--animation-duration) ease-in-out; +} + +.tabs-overview button.tab-button:not(:last-child) .tab-title { + box-shadow: 8px 0 0 -7px var(--separator-color); +} + +.tabs-overview button.tab-button:hover .tab-title { + background: var(--separator-color); + box-shadow: none; +} + +.tabs-overview button.tab-button.active .tab-title { + font-weight: 600; +} + +.tabs-overview button.tab-button::after { + content: ''; + display: block; + position: absolute; + left: 0; + bottom: 0; + right: 0; + height: 0; + width: 0%; + margin: 0 auto; + border-radius: var(--border-radius-small) var(--border-radius-small) 0 0; + background-color: var(--primary-color); + transition: width var(--animation-duration) ease-in-out, height var(--animation-duration) ease-in-out; +} + +.tabs-overview button.tab-button.active::after { + width: 100%; + box-sizing: border-box; + height: 3px; +} + + +/* + Navigation Buttons +*/ + +.section_buttons:not(:empty) { + margin-top: calc(var(--spacing-large) * 3); +} + +.section_buttons table.markdownTable { + display: block; + width: 100%; +} + +.section_buttons table.markdownTable tbody { + display: table !important; + width: 100%; + box-shadow: none; + border-spacing: 10px; +} + +.section_buttons table.markdownTable td { + padding: 0; +} + +.section_buttons table.markdownTable th { + display: none; +} + +.section_buttons table.markdownTable tr.markdownTableHead { + border: none; +} + +.section_buttons tr th, .section_buttons tr td { + background: none; + border: none; + padding: var(--spacing-large) 0 var(--spacing-small); +} + +.section_buttons a { + display: inline-block; + border: 1px solid var(--separator-color); + border-radius: var(--border-radius-medium); + color: var(--page-secondary-foreground-color) !important; + text-decoration: none; + transition: color var(--animation-duration) ease-in-out, background-color var(--animation-duration) ease-in-out; +} + +.section_buttons a:hover { + color: var(--page-foreground-color) !important; + background-color: var(--odd-color); +} + +.section_buttons tr td.markdownTableBodyLeft a { + padding: var(--spacing-medium) var(--spacing-large) var(--spacing-medium) calc(var(--spacing-large) / 2); +} + +.section_buttons tr td.markdownTableBodyRight a { + padding: var(--spacing-medium) calc(var(--spacing-large) / 2) var(--spacing-medium) var(--spacing-large); +} + +.section_buttons tr td.markdownTableBodyLeft a::before, +.section_buttons tr td.markdownTableBodyRight a::after { + color: var(--page-secondary-foreground-color) !important; + display: inline-block; + transition: color .08s ease-in-out, transform .09s ease-in-out; +} + +.section_buttons tr td.markdownTableBodyLeft a::before { + content: '〈'; + padding-right: var(--spacing-large); +} + + +.section_buttons tr td.markdownTableBodyRight a::after { + content: '〉'; + padding-left: var(--spacing-large); +} + + +.section_buttons tr td.markdownTableBodyLeft a:hover::before { + color: var(--page-foreground-color) !important; + transform: translateX(-3px); +} + +.section_buttons tr td.markdownTableBodyRight a:hover::after { + color: var(--page-foreground-color) !important; + transform: translateX(3px); +} + +@media screen and (max-width: 450px) { + .section_buttons a { + width: 100%; + box-sizing: border-box; + } + + .section_buttons tr td:nth-of-type(1).markdownTableBodyLeft a { + border-radius: var(--border-radius-medium) 0 0 var(--border-radius-medium); + border-right: none; + } + + .section_buttons tr td:nth-of-type(2).markdownTableBodyRight a { + border-radius: 0 var(--border-radius-medium) var(--border-radius-medium) 0; + } +} diff --git a/doxygen/examples/DebuggingHDF5Applications.html b/doxygen/examples/DebuggingHDF5Applications.html index 3390887a3de..495a87c6676 100644 --- a/doxygen/examples/DebuggingHDF5Applications.html +++ b/doxygen/examples/DebuggingHDF5Applications.html @@ -1,7 +1,9 @@ Debugging HDF5 Applications - + + +

Introduction

The HDF5 library contains a number of debugging features to @@ -388,5 +390,5 @@

Performance

can be parsed from program development environments like Emacs. Any function which generates an error will not be modified.

- +
diff --git a/doxygen/examples/FileFormat.html b/doxygen/examples/FileFormat.html index eff1aead0a3..8c05d0db2f9 100644 --- a/doxygen/examples/FileFormat.html +++ b/doxygen/examples/FileFormat.html @@ -4,21 +4,19 @@ HDF5 File Format Discussion + + + - - - - - - +

HDF5 File Format Discussion

Quincey Koziol
koziol@ncsa.uiuc.edu
@@ -1271,5 +1269,5 @@ - +

diff --git a/doxygen/examples/FileImageOps.html b/doxygen/examples/FileImageOps.html index 2409979ff7b..da7952ab8d9 100644 --- a/doxygen/examples/FileImageOps.html +++ b/doxygen/examples/FileImageOps.html @@ -40,7 +40,7 @@ - +
Returns the error status: 0 for success and -1 for failure.
+ diff --git a/doxygen/examples/H5.format.1.0.html b/doxygen/examples/H5.format.1.0.html index 5002695de76..17436544343 100644 --- a/doxygen/examples/H5.format.1.0.html +++ b/doxygen/examples/H5.format.1.0.html @@ -5,7 +5,7 @@ - +
@@ -4046,5 +4046,6 @@

Disk Format: Level 2c - Data Object Data StorageData of a compound datatype is stored as a contiguous stream of the items in the structure, with each item formatted according to its datatype. + diff --git a/doxygen/examples/H5.format.1.1.html b/doxygen/examples/H5.format.1.1.html index 88f92481f1a..29bebac7da9 100644 --- a/doxygen/examples/H5.format.1.1.html +++ b/doxygen/examples/H5.format.1.1.html @@ -17,7 +17,7 @@ TABLE.note {border:none; text-align:right; width:80%;} -TABLE.desc { border:solid; border-collapse:collapse; caption-size:top; text-align:left; width:80%;} +TABLE.desc { border:solid; border-collapse:collapse; caption-side:top; text-align:left; width:80%;} TABLE.desc TR { vertical-align:top;} TABLE.desc TH { border-style:ridge; font-size:larger; padding:4px; text-decoration:underline;} TABLE.desc TD { border-style:ridge; padding:4px; } @@ -31,7 +31,7 @@ - +

@@ -6435,5 +6435,6 @@

Appendix

The "unlimited size" for a size is a value with all bits set, i.e. 0xffff...ff. + diff --git a/doxygen/examples/H5.format.2.0.html b/doxygen/examples/H5.format.2.0.html index 2ad32c85f56..df139058b72 100644 --- a/doxygen/examples/H5.format.2.0.html +++ b/doxygen/examples/H5.format.2.0.html @@ -22,10 +22,11 @@ text-indent: 0px; } -h3 { +the hr tags. */ +h3 { display: block; margin-top: 8px; margin-bottom: 8px; @@ -52,20 +53,20 @@ text-indent: 0px; } - - +*/ table.format { border: solid; border-collapse: collapse; @@ -99,7 +100,7 @@ table.desc { border: solid; border-collapse: collapse; - caption-size: top; + caption-side: top; text-align: left; width: 80%; } @@ -111,14 +112,14 @@ table.desc th { border-style: ridge; font-size: larger; - padding: 4px; + */ } table.desc td { - border-style: ridge; + border-style: ridge; /* + padding: 4px; */ vertical-align: text-top; } @@ -220,7 +221,9 @@ page-break-after: auto } - + + +

@@ -15245,6 +15248,6 @@

- - + + diff --git a/doxygen/examples/H5.format.html b/doxygen/examples/H5.format.html index 023c19d7c19..303ba310299 100644 --- a/doxygen/examples/H5.format.html +++ b/doxygen/examples/H5.format.html @@ -55,18 +55,18 @@ text-indent: 0px; font-size: 100%; } - - - - table.format { border:solid; - border-collapse:collapse; - caption-side:top; - text-align:center; - width:80%; - } + } */ + /* p.item2 { margin-left: 2em; text-indent: 2em} */ + + table.format { border:solid; + border-collapse:collapse; + caption-side:top; + text-align:center; + width:80%; + } table.format th { border:ridge; padding:4px; width:25%; @@ -85,7 +85,7 @@ table.desc { border:solid; border-collapse:collapse; - caption-size:top; + caption-side:top; text-align:left; width:80%; } @@ -94,11 +94,11 @@ table.desc th { border-style:ridge; font-size:larger; padding:4px; - + /* text-decoration:underline; */ } table.desc td { border-style:ridge; - - vertical-align:text-top; + /* padding: 4px; */ + vertical-align:text-top; } table.desc caption { font-weight:bold; font-size:larger; @@ -184,7 +184,7 @@ - +
@@ -20406,6 +20406,6 @@

VIII.C. Reference Encoding (Backward Compatibility)



- + diff --git a/doxygen/hdf5_header.html b/doxygen/hdf5_header.html index 36a32653ab9..11f1f187765 100644 --- a/doxygen/hdf5_header.html +++ b/doxygen/hdf5_header.html @@ -1,27 +1,33 @@ - + - +$projectname: $title$title + $treeview $search $mathjax +$extrastylesheet - +
Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
+ - -
Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
+ + +
+ +
@@ -29,31 +35,37 @@
- + - - - + + + + + + + +
-
$projectname -  $projectnumber +
+
$projectname $projectnumber
$projectbrief
 +
$projectbrief
 $searchbox$searchbox
$searchbox
diff --git a/doxygen/hdf5doxy.css b/doxygen/hdf5doxy.css index 639843ddc7e..8fd20c0b173 100644 --- a/doxygen/hdf5doxy.css +++ b/doxygen/hdf5doxy.css @@ -1,156 +1,3 @@ - -/******** HDF5 specific CSS code ************/ - -/**** Styles removing elements ****/ - -/* remove the "modules|classes" link for module pages (they are already in the TOC) */ -div.summary { - display:none; -} - -/* remove */ -div.contents hr { - display:none; -} - -/**** ****/ - -p, dl.warning, dl.attention, dl.note -{ - max-width:60em; - text-align:justify; -} - -li { - max-width:55em; - text-align:justify; -} - -img { - border: 0; -} - -div.fragment { - display:table; /* this allows the element to be larger than its parent */ - padding: 0pt; -} -pre.fragment { - border: 1px solid #cccccc; - - margin: 2px 0px 2px 0px; - padding: 3px 5px 3px 5px; -} - -/* Common style for all HDF5's tables */ - -table.example, table.manual, table.manual-vl, table.manual-hl { - max-width:100%; - border-collapse: collapse; - border-style: solid; - border-width: 1px; - border-color: #cccccc; - font-size: 1em; - - box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); - -moz-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); - -webkit-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); -} - -table.example th, table.manual th, table.manual-vl th, table.manual-hl th { - padding: 0.5em 0.5em 0.5em 0.5em; - text-align: left; - padding-right: 1em; - color: #555555; - background-color: #F4F4E5; - - background-image: -webkit-gradient(linear,center top,center bottom,from(#FFFFFF), color-stop(0.3,#FFFFFF), color-stop(0.30,#FFFFFF), color-stop(0.98,#F4F4E5), to(#ECECDE)); - background-image: -moz-linear-gradient(center top, #FFFFFF 0%, #FFFFFF 30%, #F4F4E5 98%, #ECECDE); - filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#FFFFFF', endColorstr='#F4F4E5'); -} - -table.example td, table.manual td, table.manual-vl td, table.manual-hl td { - vertical-align:top; - border-width: 1px; - border-color: #cccccc; -} - -/* header of headers */ -table th.meta { - text-align:center; - font-size: 1.2em; - background-color:#FFFFFF; -} - -/* intermediate header */ -table th.inter { - text-align:left; - background-color:#FFFFFF; - background-image:none; - border-style:solid solid solid solid; - border-width: 1px; - border-color: #cccccc; -} - -/** class for example / output tables **/ - -table.example { -} - -table.example th { -} - -table.example td { - padding: 0.5em 0.5em 0.5em 0.5em; - vertical-align:top; -} - -/* standard class for the manual */ - -table.manual, table.manual-vl, table.manual-hl { - padding: 0.2em 0em 0.5em 0em; -} - -table.manual th, table.manual-vl th, table.manual-hl th { - margin: 0em 0em 0.3em 0em; -} - -table.manual td, table.manual-vl td, table.manual-hl td { - padding: 0.3em 0.5em 0.3em 0.5em; - vertical-align:top; - border-width: 1px; -} - -table.manual td.alt, table.manual tr.alt, table.manual-vl td.alt, table.manual-vl tr.alt { - background-color: #F4F4E5; -} - -table.manual-vl th, table.manual-vl td, table.manual-vl td.alt { - border-color: #cccccc; - border-width: 1px; - border-style: none solid none solid; -} - -table.manual-vl th.inter { - border-style: solid solid solid solid; -} - -table.manual-hl td { - border-color: #cccccc; - border-width: 1px; - border-style: solid none solid none; -} - -table td.code { - font-family: monospace; -} - -h2 { - margin-top:2em; - border-style: none none solid none; - border-width: 1px; - border-color: #cccccc; -} - /**** Table of content in the side-nav ****/ @@ -193,26 +40,6 @@ div.warningbox { border-width: 3px; } -/**** old HDF5's styles ****/ - - -table.tutorial_code td { - border-color: transparent; /* required for Firefox */ - padding: 3pt 5pt 3pt 5pt; - vertical-align: top; -} - - -/* Whenever doxygen meets a '\n' or a '
', it will put - * the text containing the character into a

. - * This little hack together with table.tutorial_code td.note - * aims at fixing this issue. */ -table.tutorial_code td.note p.starttd { - margin: 0px; - border: none; - padding: 0px; -} - div.eimainmenu { text-align: center; } @@ -256,4 +83,4 @@ a[href^="https://"]::after background-repeat: no-repeat; background-size: contain; display: inline-block; -} +} \ No newline at end of file diff --git a/doxygen/hdf5doxy_layout.xml b/doxygen/hdf5doxy_layout.xml index 2f6d800d674..d895b2dd5bd 100644 --- a/doxygen/hdf5doxy_layout.xml +++ b/doxygen/hdf5doxy_layout.xml @@ -2,21 +2,19 @@ - - - - + - - + - + + - From f8069fa8505f453afcd84f368dfc543ea7b8ee24 Mon Sep 17 00:00:00 2001 From: Allen Byrne <50328838+byrnHDF@users.noreply.github.com> Date: Mon, 15 Jul 2024 09:43:20 -0500 Subject: [PATCH 03/20] Add tools usage text as doxygen for Tools UG (#4602) --- doxygen/Doxyfile.in | 2 + doxygen/dox/Tools.dox | 29 ++ doxygen/dox/UsersGuide.dox | 2 + hl/tools/h5watch/h5watch.h | 62 ++++ release_docs/RELEASE.txt | 4 + tools/src/h5copy/h5copy.h | 72 +++++ tools/src/h5diff/h5diff_main.h | 214 +++++++++++++ tools/src/h5dump/h5dump.h | 181 +++++++++++ tools/src/h5format_convert/h5format_convert.h | 58 ++++ tools/src/h5import/h5import.h | 288 ++++++++++++++++++ tools/src/h5jam/h5jam.h | 65 ++++ tools/src/h5ls/h5ls.h | 108 +++++++ tools/src/h5repack/h5repack.h | 225 ++++++++++++++ tools/src/h5stat/h5stat.h | 65 ++++ tools/src/misc/h5clear.h | 67 ++++ tools/src/misc/h5debug.h | 31 ++ tools/src/misc/h5delete.h | 30 ++ tools/src/misc/h5mkgrp.h | 53 ++++ tools/src/misc/h5repart.h | 47 +++ tools/test/h5copy/CMakeTests.cmake | 2 +- 20 files changed, 1604 insertions(+), 1 deletion(-) create mode 100644 doxygen/dox/Tools.dox create mode 100644 hl/tools/h5watch/h5watch.h create mode 100644 tools/src/h5copy/h5copy.h create mode 100644 tools/src/h5diff/h5diff_main.h create mode 100644 tools/src/h5format_convert/h5format_convert.h create mode 100644 tools/src/h5jam/h5jam.h create mode 100644 tools/src/h5ls/h5ls.h create mode 100644 tools/src/h5stat/h5stat.h create mode 100644 tools/src/misc/h5clear.h create mode 100644 tools/src/misc/h5debug.h create mode 100644 tools/src/misc/h5delete.h create mode 100644 tools/src/misc/h5mkgrp.h create mode 100644 tools/src/misc/h5repart.h diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index 8d059bc8732..1c3698148d3 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -689,6 +689,8 @@ FILE_PATTERNS = H5*public.h H5*module.h H5*develop.h H5FD*.h \ *.F90 \ *.dox \ *.md \ + h5copy.h h5diff_main.h h5dump.h h5format_convert.h h5import.h h5jam.h h5ls.h h5repack.h h5stat.h \ + h5watch.h h5clear.h h5debug.h h5delete.h h5mkgrp.h h5repart.h \ H5Cpp.h H5AbstractDs.h H5AtomType.h H5Attribute.h H5CommonFG.h H5CompType.h \ H5DataSet.h H5DataSpace.h H5DataType.h H5OcreatProp.h H5DaccProp.h H5DcreatProp.h \ H5DxferProp.h H5EnumType.h H5Exception.h H5FaccProp.h H5FcreatProp.h H5File.h \ diff --git a/doxygen/dox/Tools.dox b/doxygen/dox/Tools.dox new file mode 100644 index 00000000000..12d2ca1e205 --- /dev/null +++ b/doxygen/dox/Tools.dox @@ -0,0 +1,29 @@ +/** @page CommandTools Command Line Tools for HDF5 Files + +Navigate back: \ref index "Main" +

+ + +\section sec_cltools Command Line Tools for HDF5 Files +There are several command line tools provided with HDF5. +\li \ref sec_cltools_h5copy +\li \ref sec_cltools_h5diff +\li \ref sec_cltools_h5dump +\li \ref sec_cltools_h5format_convert +\li \ref sec_cltools_h5import +\li \ref sec_cltools_h5jam +\li \ref sec_cltools_h5ls +\li \ref sec_cltools_h5repack +\li \ref sec_cltools_h5stat +\li \ref sec_cltools_h5clear +\li \ref sec_cltools_h5debug +\li \ref sec_cltools_h5delete +\li \ref sec_cltools_h5mkgrp +\li \ref sec_cltools_h5repart +\li \ref sec_cltools_h5watch + + +
+Navigate back: \ref index "Main" + +*/ diff --git a/doxygen/dox/UsersGuide.dox b/doxygen/dox/UsersGuide.dox index 55a1ca134b0..d036e751153 100644 --- a/doxygen/dox/UsersGuide.dox +++ b/doxygen/dox/UsersGuide.dox @@ -309,6 +309,8 @@ \ref sec_map +\ref sec_cltools + \ref sec_addition \page AR_UG Additional Resources diff --git a/hl/tools/h5watch/h5watch.h b/hl/tools/h5watch/h5watch.h new file mode 100644 index 00000000000..188707bba2b --- /dev/null +++ b/hl/tools/h5watch/h5watch.h @@ -0,0 +1,62 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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 COPYING 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. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5WATCH_H +#define H5WATCH_H + +/** \page H5TOOL_WH_UG The HDF5 h5watch Tool + * + * \section sec_cltools_h5watch h5watch + * + * \subsection subsec_cltools_h5watch_intro Introduction + * With h5watch, you can dump stats from an HDF5 file. + * + * \subsection subsec_cltools_h5watch_usage Usage + *

h5watch [OPTIONS] [OBJECT]

+ * + * \subsection subsec_cltools_h5watch_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors, --enable-error-stack=2. + * + * \subsection subsec_cltools_h5watch_options Options + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * \li --label Label members of compound typed dataset. + * \li --simple Use a machine-readable output format. + * \li --dim Monitor changes in size of dataset dimensions only. + * \li --width=N Set the number of columns to N for output.
+ * A value of 0 sets the number of columns to the + * maximum (65535). The default width is 80 columns. + * \li --polling=N Set the polling interval to N (in seconds) when the + * dataset will be checked for appended data. + * The default polling interval is 1. + * \li --fields=\ + * Display data for the fields specified in \ + * for a compound data type. + * \ can be specified as follows: + *
  • 1) A comma-separated list of field names in a + * compound data type. "," is the separator for field names while "." is the separator + * for a nested field.
    • + *
  • 2) A single field name in a compound data type. + * This option can be used multiple times.
+ * Note that backslash is the escape character to avoid + * characters in field names that conflict with the tool's separators. + * + * \subsection subsec_cltools_h5watch_objs Object + * OBJECT is specified as [\/\/\] + * \li \ Name of the HDF5 file. It may be preceded by path + * separated by slashes to the specified HDF5 file. + * \li \ Path separated by slashes to the specified dataset + * \li \ Name of the dataset + * + */ + +#endif /* H5WATCH_H */ diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt index 8b43f5ecddb..29bd8a48f4b 100644 --- a/release_docs/RELEASE.txt +++ b/release_docs/RELEASE.txt @@ -765,6 +765,10 @@ New Features Tools: ------ + - Add doxygen files for the tools + + Implement the tools usage text as pages in doxygen. + - Add option to adjust the page buffer size in tools The page buffer cache size for a file can now be adjusted using the diff --git a/tools/src/h5copy/h5copy.h b/tools/src/h5copy/h5copy.h new file mode 100644 index 00000000000..b0a684f4ab9 --- /dev/null +++ b/tools/src/h5copy/h5copy.h @@ -0,0 +1,72 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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 COPYING 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. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +#ifndef H5COPY_H +#define H5COPY_H + +/** \page H5TOOL_CP_UG The HDF5 h5copy Tool + * + * \section sec_cltools_h5copy h5copy + * + * \subsection subsec_cltools_h5copy_intro Introduction + * With h5copy, you can copy objects from an HDF5 file to another file. + * + * \subsection subsec_cltools_h5copy_usage Usage + *

h5copy [OPTIONS] [OBJECTS...]

+ * + * \subsection subsec_cltools_h5copy_objs Objects + * \li --input input file name + * \li --output output file name + * \li --source source object name + * \li --destination destination object name + * + * \subsection subsec_cltools_h5copy_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + Optional value 2 also prints file open errors, --enable-error-stack=2. + * + * \subsection subsec_cltools_h5copy_options Options + * \li --help Print a usage message and exit + * \li --parents No error if existing, make parent groups as needed + * \li --verbose Print information about OBJECTS and OPTIONS + * \li --version Print the library version number and exit + * \li --flag Flag type + * + * \subsubsection subsubsec_cltools_h5copy_options_args Flag Type Options + * Flag type is one of the following strings: + * \li shallow Copy only immediate members for groups + * \li soft Expand soft links into new objects + * \li ext Expand external links into new objects + * \li ref Copy references and any referenced objects, i.e., objects + * that the references point to.
+ * Referenced objects are copied in addition to the objects + * specified on the command line and reference datasets are + * populated with correct reference values. Copies of referenced + * datasets outside the copy range specified on the command line + * will normally have a different name from the original.
+ * (Default: Without this option, reference value(s) in any + * reference datasets are set to NULL and referenced objects are + * not copied unless they are otherwise within the copy range + * specified on the command line.) + * \li noattr Copy object without copying attributes + * \li allflags Switches all flags from the default to the non-default setting + * + * These flag types correspond to the following API symbols + * \li #H5O_COPY_SHALLOW_HIERARCHY_FLAG + * \li #H5O_COPY_EXPAND_SOFT_LINK_FLAG + * \li #H5O_COPY_EXPAND_EXT_LINK_FLAG + * \li #H5O_COPY_EXPAND_REFERENCE_FLAG + * \li #H5O_COPY_WITHOUT_ATTR_FLAG + * \li #H5O_COPY_ALL + * + */ + +#endif /* H5COPY_H */ diff --git a/tools/src/h5diff/h5diff_main.h b/tools/src/h5diff/h5diff_main.h new file mode 100644 index 00000000000..fcbf25bb02a --- /dev/null +++ b/tools/src/h5diff/h5diff_main.h @@ -0,0 +1,214 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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 COPYING 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. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +#ifndef H5DIFF_H +#define H5DIFF_H + +/** \page H5TOOL_DF_UG The HDF5 h5diff Tool + * + * \section sec_cltools_h5diff h5diff + * + * \subsection subsec_cltools_h5diff_intro Introduction + * With h5diff, you can compare objects between an HDF5 file and objects in another or the same HDF5 file. + * + * \subsection subsec_cltools_h5diff_usage Usage + *

h5diff [OPTIONS] file1 file2 [obj1[ obj2]]

+ * \li file1 File name of the first HDF5 file + * \li file2 File name of the second HDF5 file + * \li [obj1] Name of an HDF5 object, in absolute path + * \li [obj2] Name of an HDF5 object, in absolute path + * + * \subsection subsec_cltools_h5diff_error Error Report + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors, --enable-error-stack=2. + * + * \subsection subsec_cltools_h5diff_options Options + * \li --help Print a usage message and exit. + * \li --version Print the library version number and exit. + * \li --report Report mode. Print differences. + * \li --verbose Verbose mode. Print differences information and list of objects. + * \li --verbose=N Verbose mode with level. Print differences and list of objects. + * Level of detail depends on value of N: + *
  • 0 Identical to '-v' or '--verbose'.
    • + *
  • 1 All level 0 information plus one-line attribute status summary.
    • + *
  • 2 All level 1 information plus extended attribute status report.
    • + *
  • 3 All level 2 information plus file names.
+ * \li --quiet Quiet mode. Do not produce output. + * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers + * \li --vol-value-1 Value (ID) of the VOL connector to use for opening the + * first HDF5 file specified + * \li --vol-name-1 Name of the VOL connector to use for opening the first + * HDF5 file specified + * \li --vol-info-1 VOL-specific info to pass to the VOL connector used for + * opening the first HDF5 file specified + * \li --vol-value-2 Value (ID) of the VOL connector to use for opening the + * second HDF5 file specified + * \li --vol-name-2 Name of the VOL connector to use for opening the second + * HDF5 file specified + * \li --vol-info-2 VOL-specific info to pass to the VOL connector used for + * opening the second HDF5 file specified.
+ * If none of the above options are used to specify a VOL for a file, then + * the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, + * if that environment variable is unset) will be used + * \li --vfd-value-1 Value (ID) of the VFL driver to use for opening the + * first HDF5 file specified + * \li --vfd-name-1 Name of the VFL driver to use for opening the first + * HDF5 file specified + * \li --vfd-info-1 VFD-specific info to pass to the VFL driver used for + * opening the first HDF5 file specified + * \li --vfd-value-2 Value (ID) of the VFL driver to use for opening the + * second HDF5 file specified + * \li --vfd-name-2 Name of the VFL driver to use for opening the second + * HDF5 file specified + * \li --vfd-info-2 VFD-specific info to pass to the VFL driver used for + * opening the second HDF5 file specified + * \li --follow-symlinks + * Follow symbolic links (soft links and external links) and compare the + * links' target objects.
+ * If symbolic link(s) with the same name exist in the files being + * compared, then determine whether the target of each link is an existing + * object (dataset, group, or named datatype) or the link is a dangling + * link (a soft or external link pointing to a target object that does + * not yet exist). + *
  • If both symbolic links are dangling links, they are treated as being + * the same; by default, h5diff returns an exit code of 0. + * If, however, --no-dangling-links is used with --follow-symlinks, + * this situation is treated as an error and h5diff returns an + * exit code of 2.
    • + *
  • If only one of the two links is a dangling link,they are treated as + * being different and h5diff returns an exit code of 1. + * If, however, --no-dangling-links is used with --follow-symlinks, + * this situation is treated as an error and h5diff returns an + * exit code of 2.
    • + *
  • If both symbolic links point to existing objects, h5diff compares the + * two objects.
+ * If any symbolic link specified in the call to h5diff does not exist, + * h5diff treats it as an error and returns an exit code of 2. + * \li --no-dangling-links + * Must be used with --follow-symlinks option; otherwise, h5diff shows + * error message and returns an exit code of 2.
+ * Check for any symbolic links (soft links or external links) that do not + * resolve to an existing object (dataset, group, or named datatype). + * If any dangling link is found, this situation is treated as an error + * and h5diff returns an exit code of 2. + * \li --compare List objects that are not comparable + * \li --nan Avoid NaNs detection + * \li --count=C Print differences up to \b C. \b C must be a positive integer. + * \li --delta=D + * Print difference if (|a-b| > D). \b D must be a positive number, where \b a + * is the data point value in file1 and b is the data point value in file2. + * Can not use with '--relative' or '--use-system-epsilon'. + * \li --relative=R + * Print difference if (|(a-b)/b| > R). \b R must be a positive number, where \b a + * is the data point value in file1 and \b b is the data point value in file2. + * Can not use with '--delta' or '--use-system-epsilon'. + * \li --use-system-epsilon + * Print difference if (|a-b| > EPSILON), \b EPSILON is system defined value, where + * \b a is the data point value in file1 and \b b is the data point value in file2. If the system epsilon is + * not defined,one of the following predefined values will be used:
  • FLT_EPSILON = 1.19209E-07 for floating-point type
    • + *
  • DBL_EPSILON = 2.22045E-16 + * for double precision
+ * type Can not use with '--relative' or '--delta'. + * \li --exclude-path "path" Exclude the specified path to an object when + * comparing files or groups. If a group is excluded, all member objects will also be excluded. + * The specified path is excluded wherever it occurs. This flexibility enables the same option + * to exclude either objects that exist only in one file or common objects that are known to differ.
+ * When comparing files, "path" is the absolute path to the excluded object; + * when comparing groups, "path" is similar to the relative path from the group to the excluded object. This + * "path" can be taken from the first section of the output of the --verbose option.
+ * For example, if you are comparing the group /groupA + * in two files and you want to exclude + * /groupA/groupB/groupC in both files, + * the exclude option would read as follows:
+ * --exclude-path "/groupB/groupC"
+ * If there are multiple paths to an object, only the specified path(s) will be excluded; the + * comparison will include any path not explicitly excluded.
+ * This option can be used repeatedly to + * exclude multiple paths. + * \li --exclude-attribute "path/to/object/with/attribute" Exclude + * attributes on the specified path to an object when comparing files or groups.
+ * If there are multiple paths to an object, only the specified path(s) will be excluded; + * the comparison will include any path not explicitly excluded.
+ * This option can be used repeatedly to exclude multiple paths. + * + * \subsubsection subsubsec_cltools_h5diff_modee Modes of output + * \li Default mode print the number of differences found and where they occurred + * \li Report mode print the above plus the differences + * \li Verbose mode print the above plus a list of objects and warnings + * \li Quiet mode do not print output + * + * \subsubsection subsubsec_cltools_h5diff_file File comparison + * If no objects [obj1[ obj2]] are specified, the h5diff comparison proceeds as + * a comparison of the two files' root groups. That is, h5diff first compares + * the names of root group members, generates a report of root group objects + * that appear in only one file or in both files, and recursively compares + * common objects. + * + * \subsubsection subsubsec_cltools_h5diff_object Object comparison + * \li 1) Groups + * First compares the names of member objects (relative path, from the + * specified group) and generates a report of objects that appear in only + * one group or in both groups. Common objects are then compared recursively. + * \li 2) Attributes and Datasets + * Array rank and dimensions, datatypes, and data values are compared. + * \li 3) Datatypes + * The comparison is based on the return value of H5Tequal. + * \li 4) Symbolic links + * The paths to the target objects are compared. + * (The option --follow-symlinks overrides the default behavior when + * symbolic links are compared.) + * + * \subsubsection subsubsec_cltools_h5diff_subset Subsetting Options + * \li --no-compact-subset Disable compact form of subsetting and allow the use + * of "[" in dataset names. + * + * Subsetting is available by using the fcompact form of subsetting, as follows: + * obj1 /foo/mydataset[START;STRIDE;COUNT;BLOCK] + * + * It is not required to use all parameters, but until the last parameter value used, + * all of the semicolons (;) are required, even when a parameter value is not specified. + * + * Example: + * obj1 /foo/mydataset[START;;COUNT;BLOCK] + * obj1 /foo/mydataset[START] + * + * The \b STRIDE, \b COUNT, and \b BLOCK parameters are optional and will default to 1 in + * each dimension. \b START is optional and will default to 0 in each dimension. + * Each of \b START, \b STRIDE, \b COUNT, and \b BLOCK must be a comma-separated list of integers with + * one integer for each dimension of the dataset. + * + * \subsubsection subsubsec_cltools_h5diff_exit Exit code + * \li 0 if no differences + * \li 1 if differences found + * \li 2 if error + * + * \subsubsection subsubsec_cltools_h5diff_examples Examples + * \li 1) h5diff file1 file2 /g1/dset1 /g1/dset2 + * + * Compares object '/g1/dset1' in file1 with '/g1/dset2' in file2 + * + * \li 2) h5diff file1 file2 /g1/dset1 + * + * Compares object '/g1/dset1' in both files + * + * \li 3) h5diff file1 file2 + * + * Compares all objects in both files + * + * Notes: + * file1 and file2 can be the same file. + * Use h5diff file1 file1 /g1/dset1 /g1/dset2 to compare '/g1/dset1' and '/g1/dset2' in the same file + * + */ + +#endif /* H5DIFF_H */ diff --git a/tools/src/h5dump/h5dump.h b/tools/src/h5dump/h5dump.h index 5deb95190a9..879206dfa62 100644 --- a/tools/src/h5dump/h5dump.h +++ b/tools/src/h5dump/h5dump.h @@ -12,6 +12,187 @@ #ifndef H5DUMP_H #define H5DUMP_H +/** \page H5TOOL_DP_UG The HDF5 h5dump Tool + * + * \section sec_cltools_h5dump h5dump + * + * \subsection subsec_cltools_h5dump_intro Introduction + * With h5dump, you can display objects from an HDF5 file. + * + * \subsection subsec_cltools_h5dump_usage Usage + *

h5dump [OPTIONS] [files

+ * + * \subsection subsec_cltools_h5dump_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors, --enable-error-stack=2. + * + * \subsection subsec_cltools_h5dump_options Options + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * + * \subsection subsec_cltools_h5dump_options_file File Options + * \li --contents Print a list of the file contents, group and dataset, + * names and values, then exit. Optional value 1 also prints attributes, --contents=1. + * \li --superblock Print the content of the super block + * \li --header Print the header only; no data is displayed + * \li --filedriver=D Specify which driver to open the file with + * \li --output=F Output raw data into file F + * \li --binary=B Binary file output, of form B + * \li --ddl=F Output ddl text into file F + * Use blank(empty) filename F to suppress ddl display + * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers + * \li --s3-cred=\ Supply S3 authentication information to "ros3" vfd. + * \code \ :: "(,,)" \endcode + * If absent or \code \ -> "(,,)" \endcode, no authentication. + * Has no effect if filedriver is not "ros3". + * \li --hdfs-attrs=\ Supply configuration information for HDFS file access. + * For use with --filedriver=hdfs + * \code \ :: (\,\, + * \,\, + * \) \endcode + * Any absent attribute will use a default value. + * \li --vol-value Value (ID) of the VOL connector to use for opening the HDF5 file specified + * \li --vol-name Name of the VOL connector to use for opening the HDF5 file specified + * \li --vol-info VOL-specific info to pass to the VOL connector used for + * opening the HDF5 file specified.
+ * If none of the above options are used to specify a VOL, then + * the VOL named by \b HDF5_VOL_CONNECTOR (or the native VOL connector, + * if that environment variable is unset) will be used + * \li--vfd-value Value (ID) of the VFL driver to use for opening the HDF5 file specified + * \li --vfd-name Name of the VFL driver to use for opening the HDF5 file specified + * \li --vfd-info VFD-specific info to pass to the VFL driver used for + * opening the HDF5 file specified + * + * \subsection subsec_cltools_h5dump_options_obj Object Options + * \li --attribute=P Print the specified attribute + * If an attribute name contains a slash (/), escape the + * slash with a preceding backslash (\). + * (See example section below.) + * \li --dataset=P Print the specified dataset + * \li --group=P Print the specified group and all members + * \li --soft-link=P Print the value(s) of the specified soft link + * \li --datatype=P Print the specified named datatype + * \li --any_path=P Print any attribute, dataset, group, datatype, or link that matches P + * P can be the absolute path or just a relative path. + * \li --onlyattr Print the header and value of attributes + * Optional value 0 suppresses printing attributes. + * \li --vds-view-first-missing Set the VDS bounds to first missing mapped elements. + * \li --vds-gap-size=N Set the missing file gap size, N=non-negative integers + * + * \subsection subsec_cltools_h5dump_options_prop Object Property Options + * \li --object-ids Print the object ids + * \li --properties Print dataset filters, storage layout and fill value + * \li --packedbits=L Print packed bits as unsigned integers, using mask + * format L for an integer dataset specified with + * option -d. L is a list of offset,length values, + * separated by commas. Offset is the beginning bit in + * the data value and length is the number of bits of + * the mask. + * \li --region Print dataset pointed by region references + * + * \subsection subsec_cltools_h5dump_options_fmt Formatting Options + * \li --escape Escape non printing characters + * \li --string Print 1-byte integer datasets as ASCII + * \li --noindex Do not print array indices with the data + * \li --format=T Set the floating point output format + * \li --sort_by=Q Sort groups and attributes by index Q + * \li --sort_order=Z Sort groups and attributes by order Z + * \li --no-compact-subset Disable compact form of subsetting and allow the use + * of "[" in dataset names. + * \li --width=N Set the number of columns of output. A value of 0 (zero) + * sets the number of columns to the maximum (65535). + * Default width is 80 columns. + * + * \subsection subsec_cltools_h5dump_options_xml XML Options + * \li --xml Output in XML using Schema + * \li --use-dtd Output in XML using DTD + * \li --xml-dtd=U Use the DTD or schema at U + * \li --xml-ns=S (XML Schema) Use qualified names n the XML + * ":": no namespace, default: "hdf5:" + * E.g., to dump a file called "-f", use h5dump -- -f + * + * \subsection subsec_cltools_h5dump_options_subset Subsetting Options + * Subsetting is available by using the following options with a dataset + * option. Subsetting is done by selecting a hyperslab from the data. + * Thus, the options mirror those for performing a hyperslab selection.
+ * One of the \b START, \b COUNT, \b STRIDE, or \b BLOCK parameters are mandatory if you do subsetting. + * The \b STRIDE, \b COUNT, and \b BLOCK parameters are optional and will default to 1 in + * each dimension. \b START is optional and will default to 0 in each dimension. + * + * \li --start=START Offset of start of subsetting selection + * \b START - is a list of integers, the number of which are equal to the + * number of dimensions in the dataspace being queried.
+ * \li --stride=STRIDE Hyperslab stride + * \b COUNT - is a list of integers, the number of which are equal to the + * number of dimensions in the dataspace being queried.
+ * \li --count=COUNT Number of blocks to include in selection + * \b STRIDE - is a list of integers, the number of which are equal to the + * number of dimensions in the dataspace being queried.
+ * \li --block=BLOCK Size of block in hyperslab + * \b BLOCK - is a list of integers, the number of which are equal to the + * number of dimensions in the dataspace being queried.
+ * (Alternate compact form of subsetting is described in the Reference Manual) + * + * \subsubsection subsubsec_cltools_h5dump_options_args Option Argument Conventions + * \li D - is the file driver to use in opening the file. Acceptable values are available + * from https://support.hdfgroup.org/documentation/HDF5/registered_virtual_file_drivers_vfds.html. Without + * the file driver flag, the file will be opened with each driver in turn and in the order specified above + * until one driver succeeds in opening the file. See examples below for family, split, and multi driver + * special file name usage. + * + * \li F - is a filename. + * \li P - is the full path from the root group to the object. + * \li N - is an integer greater than 1. + * \li T - is a string containing the floating point format, e.g '%.3f' + * \li U - is a URI reference (as defined in [IETF RFC 2396], + * updated by [IETF RFC 2732]) + * \li B - is the form of binary output: NATIVE for a memory type, FILE for the + * file type, LE or BE for pre-existing little or big endian types. + * Must be used with -o (output file) and it is recommended that + * -d (dataset) is used. B is an optional argument, defaults to NATIVE + * \li Q - is the sort index type. It can be "creation_order" or "name" (default) + * \li Z - is the sort order type. It can be "descending" or "ascending" (default) + * + * \subsection subsec_cltools_h5dump_examples Usage Examples + * + * \li 1) Attribute foo of the group /bar_none in file quux.h5 + * + * h5dump --attribute=/bar_none/foo quux.h5 + * + * \li 2) Attribute "high/low" of the group /bar_none in the file quux.h5 + * + * h5dump --attribute="/bar_none/high\/low" quux.h5 + * + * \li 3) Selecting a subset from dataset /foo in file quux.h5 + * + * h5dump --dataset=/foo --start="0,1" --stride="1,1" --count="2,3" --block="2,2" quux.h5 + * + * \li 4) Saving dataset 'dset' in file quux.h5 to binary file 'out.bin' using a little-endian type + * + * h5dump --dataset=/dset --binary=LE --output=out.bin quux.h5 + * + * \li 5) Display two packed bits (bits 0-1 and bits 4-6) in the dataset /dset + * + * h5dump -d-dataset=/dset --packedbits=0,1,4,3 quux.h5 + * + * \li 6) Dataset foo in files file1.h5 file2.h5 file3.h5 + * + * h5dump --dataset=/foo file1.h5 file2.h5 file3.h5 + * + * \li 7) Dataset foo in split files splitfile-m.h5 splitfile-r.h5 + * + * h5dump --dataset=/foo --filedriver=split splitfile + * + * \li 8) Dataset foo in multi files mf-s.h5, mf-b.h5, mf-r.h5, mf-g.h5, mf-l.h5 and mf-o.h5 + * + * h5dump --dataset=/foo --filedriver=multi mf + * + * \li 9) Dataset foo in family files fam00000.h5 fam00001.h5 and fam00002.h5 + * + * h5dump --dataset=/foo --filedriver=family fam%05d.h5 + * + */ + #include "hdf5.h" #include "H5private.h" #include "h5tools.h" diff --git a/tools/src/h5format_convert/h5format_convert.h b/tools/src/h5format_convert/h5format_convert.h new file mode 100644 index 00000000000..5f101dac52c --- /dev/null +++ b/tools/src/h5format_convert/h5format_convert.h @@ -0,0 +1,58 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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 COPYING 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. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5FORMAT_CONVERT_H +#define H5FORMAT_CONVERT_H + +/** \page H5TOOL_FC_UG The HDF5 h5format_convert Tool + * + * \section sec_cltools_h5format_convert h5format_convert + * + * \subsection subsec_cltools_h5format_convert_intro Introduction + * With h5format_convert, you can convert a datasets format in an HDF5 file. + * + * \subsection subsec_cltools_h5format_convert_usage Usage + *

h5format_convert [OPTIONS] file_name

+ * + * \subsection subsec_cltools_h5format_convert_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors, --enable-error-stack=2. + * + * \subsection subsec_cltools_h5format_convert_options Options + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * \li --verbose Turn on verbose mode + * \li --dname=dataset_name Pathname for the dataset + * \li --noop Perform all the steps except the actual conversion + * + * \subsubsection subsubsec_cltools_h5format_convert_examples Usage Examples + * \li 1) h5format_convert --dname=/group/dataset file_name + * + * Convert the dataset in the HDF5 file : + * - chunked dataset: convert the chunk indexing type to version 1 B-tree + * - compact/contiguous dataset: downgrade the layout version to 3 + * - virtual dataset: no action + * + * \li 2) h5format_convert file_name + * + * Convert all datasets in the HDF5 file : + * - chunked dataset: convert the chunk indexing type to version 1 B-tree + * - compact/contiguous dataset: downgrade the layout version to 3 + * - virtual dataset: no action + * + * \li 3) h5format_convert --noop --dname=/group/dataset file_name + * + * Go through all the steps except the actual conversion when + * converting the dataset in the HDF5 file . + * + */ + +#endif /* H5FORMAT_CONVERT_H */ diff --git a/tools/src/h5import/h5import.h b/tools/src/h5import/h5import.h index 86a27889c9b..5b03780674e 100644 --- a/tools/src/h5import/h5import.h +++ b/tools/src/h5import/h5import.h @@ -19,6 +19,294 @@ #ifndef H5IMPORT_H #define H5IMPORT_H +/** \page H5TOOL_IM_UG The HDF5 h5import Tool + * + * \section sec_cltools_h5import h5import + * + * \subsection subsec_cltools_h5import_intro Introduction + * With h5import, you can convert data stored in one or more ASCII or binary files + * into one or more datasets (in accordance with the + * user-specified type and storage properties) in an existing + * or new HDF5 file. + * + * \subsection subsec_cltools_h5import_desc Description + * The primary objective of the utility is to convert floating + * point or integer data stored in \b ASCII text or binary form + * into a dataset according to the type and storage properties + * specified by the user. The utility can also accept \b ASCII + * text files and store the contents in a compact form as an + * array of one-dimensional strings. + * + * The input data to be written as a dataset can be provided + * to the utility in one of the following forms: + * \li 1. ASCII text file with numeric data (floating point or + * integer data) + * \li 2. Binary file with native floating point data (32-bit or + * 64-bit) + * \li 3. Binary file with native integer (signed or unsigned) + * data (8-bit or 16-bit or 32-bit or 64-bit) + * \li 4. ASCII text file containing strings (text data) + * + * Every input file is associated with a configuration file + * also provided as an input to the utility. (See Section + * \ref subsec_cltools_h5import_config to know how it is to be organized). + * The class, size and dimensions of the input data is + * specified in this configuration file. A point to note is + * that the floating point data in the \b ASCII text file may be + * organized in the fixed floating form (for example 323.56) + * or in scientific notation (for example 3.23E+02). A + * different input-class specification is to be used for both forms. + * + * The utility extracts the input data from the input file + * according to the specified parameters and saves it into + * an HDF5 dataset. + * + * The user can specify output type and storage properties in + * the configuration file. The user is required to specify the + * path of the dataset. If the groups in the path leading to + * the dataset do not exist, the groups will be created by the + * utility. If no group is specified, the dataset will be + * created under the root group. + * + * In addition to the name, the user is also required to + * provide the class and size of output data to be written to + * the dataset and may optionally specify the output-architecture, + * and the output-byte-order. If output-architecture is not + * specified, the default is \b NATIVE. Output-byte-orders are fixed + * for some architectures and may be specified only if output- + * architecture is \b IEEE, \b UNIX or \b STD. + * + * Also, layout and other storage properties such as + * compression, external storage and extendible datasets may be + * optionally specified. The layout and storage properties + * denote how raw data is to be organized on the disk. If these + * options are not specified, the default is \b Contiguous layout + * and storage. + * + * The dataset can be organized in any of the following ways: + * \li 1. Contiguous + * \li 2. Chunked + * \li 3. External Storage File (has to be contiguous) + * \li 4. Extendible data sets(has to be chunked) + * \li 5. Compressed (has to be chunked) + * \li 6. Compressed & Extendible (has to be chunked) + * + * If the user wants to store raw data in a non-HDF5 file then + * the external storage file option is to be used and the name + * of the file is to be specified. + * + * If the user wants the dimensions of the dataset to be + * unlimited, the extendible data set option can be chosen. + * + * The user may also specify the type of compression and the + * level to which the data set must be compressed by setting + * the compressed option. + * + * \subsection subsec_cltools_h5import_usage Usage + *

h5import -h[elp], OR h5import \ -c[onfig] \ [\ + * -c[config]\...] -o[utfile] \

+ * + * \subsection subsec_cltools_h5import_help Help + * \li -h[elp] Print a usage message and exit + * + * \subsubsection subsubsec_cltools_h5import_options Program Options + * \li \ + * Name of the Input file(s), containing a + * single n-dimensional floating point or integer array + * in either ASCII text, native floating point(32-bit + * or 64-bit) or native integer(8-bit or 16-bit or + * 32-bit or 64-bit). Data to be specified in the order + * of fastest changing dimensions first. + * + * \li -c[config] \ + * Every input file should be associated with a + * configuration file and this is done by the -c option. + * \ is the name of the configuration file. + * (See Section \ref subsec_cltools_h5import_config). + * + * \li -o[utfile] \ + * Name of the HDF5 output file. Data from one or more + * input files are stored as one or more data sets in + * \. The output file may be an existing file or + * it may be new, in which case it will be created. + * + * \subsection subsec_cltools_h5import_config Configuration File + * The configuration file is an ASCII text file and must be + * the ddl formatted file (without data values) produced by \b h5dump + * when used with the options \code -o outfilename -b \endcode of a single dataset (-d) + * OR organized as CONFIG-KEYWORD VALUE pairs, one pair on each + * line. + * + * The configuration file may have the following keywords each + * followed by an acceptable value. + * + * \subsubsection subsubsec_cltools_h5import_config_req Required KEYWORDS + * \li PATH + * \li INPUT-CLASS + * \li INPUT-SIZE + * \li INPUT-BYTE-ORDER + * \li RANK + * \li DIMENSION-SIZES + * \li OUTPUT-CLASS + * \li OUTPUT-SIZE + * + * \subsubsection subsubsec_cltools_h5import_config_opt Optional KEYWORDS + * \li OUTPUT-ARCHITECTURE + * \li OUTPUT-BYTE-ORDER + * \li CHUNKED-DIMENSION-SIZES + * \li COMPRESSION-TYPE + * \li COMPRESSION-PARAM + * \li EXTERNAL-STORAGE + * \li MAXIMUM-DIMENSIONS + * + * \subsubsection subsubsec_cltools_h5import_config_val Values for keywords + * \li PATH + * Strings separated by spaces to represent + * the path of the dataset. If the groups in + * the path do not exist, they will be created. + * For example, + *
  • PATH grp1/grp2/dataset1
    • + *
  • PATH: keyword
    • + *
  • grp1: group under the root. If non-existent will be created
    • + *
  • grp2: group under grp1. If non-existent will be created under grp1
    • + *
  • dataset1: the name of the dataset to be created
+ * + * \li INPUT-CLASS + * String denoting the type of input data. + *
  • TEXTIN
    • + *
  • TEXTFP
    • + *
  • FP
    • + *
  • IN
    • + *
  • STR
    • + *
  • TEXTUIN
    • + *
  • UIN
+ * \b INPUT-CLASS "TEXTIN" denotes an ASCII text file with signed integer data in ASCII form, + * \b INPUT-CLASS "TEXTUIN" denotes an ASCII text file with unsigned integer data in ASCII form, + * "TEXTFP" denotes an ASCII text file containing floating point data in the fixed notation + * (325.34),
+ * "FP" denotes a floating point binary file, + * "IN" denotes a signed integer binary file, + * "UIN" denotes an unsigned integer binary file, + * & "STR" denotes an ASCII text file the contents of which should be stored as a 1-D + * array of strings.
+ * If \b INPUT-CLASS is "STR", then \b RANK, + * \b DIMENSION-SIZES, \b OUTPUT-CLASS, \b OUTPUT-SIZE, + * \b OUTPUT-ARCHITECTURE and \b OUTPUT-BYTE-ORDER + * will be ignored. + * + * \li INPUT-SIZE + * Integer denoting the size of the input data (8, 16, 32, 64). + *
  • For floating point, \b INPUT-SIZE can be 32 or 64.
    • + *
  • For integers (signed and unsigned) \b INPUT-SIZE can be 8, 16, 32 or 64.
+ * + * \li RANK + * Integer denoting the number of dimensions. + * + * \li DIMENSION-SIZES + * Integers separated by spaces to denote the dimension sizes for the number of dimensions + * determined by rank. + * + * \li OUTPUT-CLASS + * String denoting data type of the dataset to be written ("IN","FP", "UIN") + * + * \li OUTPUT-SIZE + * Integer denoting the size of the data in the output dataset to be written. + * If \b OUTPUT-CLASS is "FP", \b OUTPUT-SIZE can be 32 or 64. + * If \b OUTPUT-CLASS is "IN" or "UIN", \b OUTPUT-SIZE can be 8, 16, 32 or 64. + * + * \li OUTPUT-ARCHITECTURE + * \b STRING denoting the type of output architecture. Can accept the following values + *
  • STD
    • + *
  • IEEE
    • + *
  • INTEL
    • + *
  • CRAY
    • + *
  • MIPS
    • + *
  • ALPHA
    • + *
  • NATIVE (default)
    • + *
  • UNIX
+ * + * \li OUTPUT-BYTE-ORDER + * String denoting the output-byte-order. Ignored if the \b OUTPUT-ARCHITECTURE is not specified or + * if it is \b IEEE, \b UNIX or \b STD. Can accept the following values. + *
  • BE (default)
    • + *
  • LE
+ * + * \li CHUNKED-DIMENSION-SIZES + * Integers separated by spaces to denote the dimension sizes of the chunk for the number of + * dimensions determined by rank. Required field to denote that the dataset will be stored with + * chunked storage. If this field is absent the dataset will be stored with contiguous storage. + * + * \li COMPRESSION-TYPE + * String denoting the type of compression to be used with the chunked storage. Requires the + * \b CHUNKED-DIMENSION-SIZES to be specified. The only currently supported compression method is \b GZIP. + * Will accept the following value + *
  • GZIP
+ * + * \li COMPRESSION-PARAM + * Integer used to denote compression level and this option is to be always specified when + * the \b COMPRESSION-TYPE option is specified. The values are applicable only to \b GZIP + * compression.
+ * Value 1-9: The level of Compression.
+ * 1 will result in the fastest compression while 9 will result in + * the best compression ratio.
+ * The default level of compression is 6. + * + * \li EXTERNAL-STORAGE + * String to denote the name of the non-HDF5 file to store data to. Cannot be used if \b + * CHUNKED-DIMENSIONS or \b COMPRESSION-TYPE or \b EXTENDIBLE-DATASET is specified. Value + * \: the name of the external file as a string to be used. + * + * \li MAXIMUM-DIMENSIONS + * Integers separated by spaces to denote the maximum dimension sizes of all the + * dimensions determined by rank. Requires the \b CHUNKED-DIMENSION-SIZES to be specified. A value of + * -1 for any dimension implies \b UNLIMITED \b DIMENSION size for that particular dimension. + * + * \subsection subsec_cltools_h5import_examples Usage Examples + * \li Configuration File may look like + * \code + * PATH work h5 pkamat First-set + * INPUT-CLASS TEXTFP + * RANK 3 + * DIMENSION-SIZES 5 2 4 + * OUTPUT-CLASS FP + * OUTPUT-SIZE 64 + * OUTPUT-ARCHITECTURE IEEE + * OUTPUT-BYTE-ORDER LE + * CHUNKED-DIMENSION-SIZES 2 2 2 + * \endcode + * The above configuration will accept a floating point array + * (5 x 2 x 4) in an ASCII file with the rank and dimension sizes + * specified and will save it in a chunked dataset (of pattern + * 2 X 2 X 2) of 64-bit floating point in the little-endian order + * and IEEE architecture. The dataset will be stored at + * "/work/h5/pkamat/First-set" + * + * \li Another configuration could be + * \code + * PATH Second-set + * INPUT-CLASS IN + * RANK 5 + * DIMENSION-SIZES 6 3 5 2 4 + * OUTPUT-CLASS IN + * OUTPUT-SIZE 32 + * CHUNKED-DIMENSION-SIZES 2 2 2 2 2 + * EXTENDIBLE-DATASET 1 3 + * COMPRESSION-TYPE GZIP + * COMPRESSION-PARAM 7 + * \endcode + * The above configuration will accept an integer array + * (6 X 3 X 5 x 2 x 4) in a binary file with the rank and + * dimension sizes specified and will save it in a chunked dataset + * (of pattern 2 X 2 X 2 X 2 X 2) of 32-bit floating point in + * native format (as output-architecture is not specified). The + * first and the third dimension will be defined as unlimited. The + * dataset will be compressed using GZIP and a compression level + * of 7.
+ * The dataset will be stored at \code /Second-set \endcode + * + * + */ + /* * state table tokens */ diff --git a/tools/src/h5jam/h5jam.h b/tools/src/h5jam/h5jam.h new file mode 100644 index 00000000000..7d3cca65535 --- /dev/null +++ b/tools/src/h5jam/h5jam.h @@ -0,0 +1,65 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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 COPYING 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. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5JAM_H +#define H5JAM_H + +/** \page H5TOOL_JAM_UG The HDF5 h5jam/h5unjam Tool + * + * \section sec_cltools_h5jam h5jam and h5unjam + * + * \subsection subsec_cltools_h5jam_intro Introduction + * \li h5jam Adds user block to the front of an HDF5 file and creates a new concatenated file. + * \li h5unjam Splits an HDF5 file into two files, one containing the user block data and the other the HDF5 + * data. + * + * \subsection subsec_cltools_h5jam_usage Usage + *

h5jam -i \ -u \ [-o \] [--clobber]

+ *

h5unjam -i \ [-o \ ] [-u \ | --delete]

+ * + * \subsection subsec_cltools_h5jam_options h5jam Options + * \li -i in_file.h5 Specifies the input HDF5 file. + * \li -u in_user_file Specifies the file to be inserted into the user block. + * Can be any file format except an HDF5 format. + * \li -o out_file.h5 Specifies the output HDF5 file. + * If not specified, the user block will be concatenated in + * place to the input HDF5 file. + * \li --clobber Wipes out any existing user block before concatenating + * the given user block. + * The size of the new user block will be the larger of: + * - the size of existing user block in the input HDF5 file + * - the size of user block required by new input user file + * (size = 512 x 2N, N is positive integer.) + * \li -h Prints a usage message and exits. + * \li -V Prints the HDF5 library version and exits. + * + * \subsection subsec_cltools_h5unjam_options h5unjam Options + * \li -i in_file.h5 Specifies the HDF5 as input. If the input HDF5 file + * contains no user block, exit with an error message. + * \li -o out_file.h5 Specifies output HDF5 file without a user block. + * If not specified, the user block will be removed from the + * input HDF5 file. + * \li -u out_user_file + * Specifies the output file containing the data from the + * user block. + * Cannot be used with --delete option. + * \li --delete Remove the user block from the input HDF5 file. The content + * of the user block is discarded. + * Cannot be used with the -u option. + * \li -h Prints a usage message and exits. + * \li -V Prints the HDF5 library version and exits. + * + * If neither --delete nor -u is specified, the user block from the input + * file will be displayed to stdout. + * + */ + +#endif /* H5JAM_H */ diff --git a/tools/src/h5ls/h5ls.h b/tools/src/h5ls/h5ls.h new file mode 100644 index 00000000000..d72c1be10d4 --- /dev/null +++ b/tools/src/h5ls/h5ls.h @@ -0,0 +1,108 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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 COPYING 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. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5LS_H +#define H5LS_H + +/** \page H5TOOL_LS_UG The HDF5 h5ls Tool + * + * \section sec_cltools_h5ls h5ls + * + * \subsection subsec_cltools_h5ls_intro Introduction + * With h5ls, you can dump objects from an HDF5 file. + * + * \subsection subsec_cltools_h5ls_usage Usage + *

h5ls [OPTIONS] file[/OBJECT] [file[/[OBJECT]...]

+ * + * \subsection subsec_cltools_h5ls_objs file/OBJECT + * Each object consists of an HDF5 file name optionally followed by a + * slash and an object name within the file (if no object is specified + * within the file then the contents of the root group are displayed). + * The file name may include a printf(3C) integer format such as + * "%05d" to open a file family. + * + * \subsection subsec_cltools_h5ls_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors, --enable-error-stack=2. + * + * \subsection subsec_cltools_h5ls_options Options + * \li --help Print a usage message and exit + * \li --address Print raw data address. If dataset is contiguous, address + * is offset in file of beginning of raw data. If chunked, + * returned list of addresses indicates offset of each chunk. + * Must be used with --verbose option. + * Provides no information for non-dataset objects. + * \li --data Print the values of datasets + * \li --follow-symlinks + * Follow symbolic links (soft links and external links) + * to display target object information.
+ * Without this option, h5ls identifies a symbolic link + * as a soft link or external link and prints the value + * assigned to the symbolic link; it does not provide any + * information regarding the target object or determine + * whether the link is a dangling link. + * \li --no-dangling-links + * Must be used with --follow-symlinks option; + * otherwise, h5ls shows error message and returns an exit + * code of 1.
+ * Check for any symbolic links (soft links or external links) + * that do not resolve to an existing object (dataset, group, + * or named datatype).
+ * If any dangling link is found, this situation is treated + * as an error and h5ls returns an exit code of 1. + * \li --full Print full path names instead of base names + * \li --group Show information about a group, not its contents + * \li --label Label members of compound datasets + * \li --recursive List all groups recursively, avoiding cycles + * \li --string Print 1-byte integer datasets as ASCII + * \li --simple Use a machine-readable output format + * \li --width=N Set the number of columns of output + * \li --verbose Generate more verbose output + * \li --version Print the library version number and exit + * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers + * \li --vfd=DRIVER Use the specified virtual file driver + * \li --hexdump Show raw data in hexadecimal format + * \li --s3-cred=C Supply S3 authentication information to "ros3" vfd. + * Accepts tuple of \code (\,\,\) \endcode. + * If absent or C = \code (,,) \endcode defaults to no-authentication. + * Has no effect if vfd flag not set to "ros3". + * \li --hdfs-attrs=A Supply configuration information to Hadoop VFD. + * Accepts tuple of \code (\,\, + * ...\,\,\) \endcode + * If absent or A == \code (,,,,) \endcode all default values are used. + * Has no effect if vfd flag is not 'hdfs'. + * \li --vol-value Value (ID) of the VOL connector to use for opening the + * HDF5 file specified + * \li --vol-name Name of the VOL connector to use for opening the + * HDF5 file specified + * \li --vol-info VOL-specific info to pass to the VOL connector used for + * opening the HDF5 file specified + * If none of the above options are used to specify a VOL, then + * the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, + * if that environment variable is unset) will be used + * \li --vfd-value Value (ID) of the VFL driver to use for opening the + * HDF5 file specified + * \li --vfd-name Name of the VFL driver to use for opening the + * HDF5 file specified + * \li --vfd-info VFD-specific info to pass to the VFL driver used for + * opening the HDF5 file specified + * + * \subsubsection subsubsec_cltools_h5ls_options_depre Deprecated Options + * The following options have been removed in HDF5 1.12. Use the indicated + * replacement option in all work. + * \li --external Follow external links.
+ * Replaced by --follow-symlinks. + * \li --errors Show all HDF5 error reporting
+ * Replaced by --enable-error-stack. + * + */ + +#endif /* H5LS_H */ diff --git a/tools/src/h5repack/h5repack.h b/tools/src/h5repack/h5repack.h index cc724a067cf..2977ffab6db 100644 --- a/tools/src/h5repack/h5repack.h +++ b/tools/src/h5repack/h5repack.h @@ -13,6 +13,231 @@ #ifndef H5REPACK_H #define H5REPACK_H +/** \page H5TOOL_RP_UG The HDF5 h5repack Tool + * + * \section sec_cltools_h5repack h5repack + * + * \subsection subsec_cltools_h5repack_intro Introduction + * With h5repack, you can write an HDF5 file to a new file and change the layout for objects in the new file. + * + * \subsection subsec_cltools_h5repack_usage Usage + *

h5repack [OPTIONS] file1 file2

+ * \li file1 Input HDF5 File + * \li file2 Output HDF5 File + * + * \subsection subsec_cltools_h5repack_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors, --enable-error-stack=2. + * + * \subsection subsec_cltools_h5repack_options Options + * \li --help Print a usage message and exit + * \li --verbose=N Verbose mode, print object information. + * N - is an integer greater than 1, 2 displays read/write timing + * \li --version Print the library version number and exit + * \li --native Use a native HDF5 type when repacking + * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers + * \li --src-vol-value Value (ID) of the VOL connector to use for opening the + * input HDF5 file specified + * \li --src-vol-name Name of the VOL connector to use for opening the input + * HDF5 file specified + * \li --src-vol-info VOL-specific info to pass to the VOL connector used for + * opening the input HDF5 file specified + * \li --dst-vol-value Value (ID) of the VOL connector to use for opening the + * output HDF5 file specified + * \li --dst-vol-name Name of the VOL connector to use for opening the output + * HDF5 file specified + * \li --dst-vol-info VOL-specific info to pass to the VOL connector used for + * opening the output HDF5 file specified + * \li --src-vfd-value Value (ID) of the VFL driver to use for opening the + * input HDF5 file specified + * \li --src-vfd-name Name of the VFL driver to use for opening the input + * HDF5 file specified + * \li --src-vfd-info VFD-specific info to pass to the VFL driver used for + * opening the input HDF5 file specified + * \li --dst-vfd-value Value (ID) of the VFL driver to use for opening the + * output HDF5 file specified + * \li --dst-vfd-name Name of the VFL driver to use for opening the output + * HDF5 file specified + * \li --dst-vfd-info VFD-specific info to pass to the VFL driver used for + * opening the output HDF5 file specified + * \li --latest Use latest version of file format + * This option will take precedence over the options + * --low and --high + * \li --low=BOUND The low bound for library release versions to use + * when creating objects in the file + * (default is #H5F_LIBVER_EARLIEST) + * \li --high=BOUND The high bound for library release versions to use + * when creating objects in the file + * (default is #H5F_LIBVER_LATEST) + * \li --merge Follow external soft link recursively and merge data + * \li --prune Do not follow external soft links and remove link + * \li --merge --prune Follow external link, merge data and remove dangling link + * \li --compact=L1 Maximum number of links in header messages + * \li --indexed=L2 Minimum number of links in the indexed format + * \li --ssize=S[:F] Shared object header message minimum size + * \li --minimum=M Do not apply the filter to datasets smaller than M + * \li --file=E Name of file E with the --file and --layout options + * \li --ublock=U Name of file U with user block data to be added + * \li --block=B Size of user block to be added + * \li --metadata_block_size=A Metadata block size for #H5Pset_meta_block_size + * \li --threshold=T Threshold value for #H5Pset_alignment + * \li --alignment=A Alignment value for #H5Pset_alignment + * \li --sort_by=Q Sort groups and attributes by index Q + * \li --sort_order=Z Sort groups and attributes by order Z + * \li --filter=FILT Filter type + * \li --layout=LAYT Layout type + * \li --fs_strategy=FS_STRATEGY File space management strategy for + * #H5Pset_file_space_strategy + * \li --fs_persist=FS_PERSIST Persisting or not + * persisting free-space for #H5Pset_file_space_strategy + * \li --fs_threshold=FS_THRESHOLD : Free-space section + * threshold for #H5Pset_file_space_strategy + * \li --fs_pagesize=FS_PAGESIZE File space page size for #H5Pset_file_space_page_size + * + * \subsubsection subsubsec_cltools_h5repack_options_args Arguments to Certain Options + * \li M - is an integer greater than 1, size of dataset in bytes (default is 0) + * \li E - is a filename. + * \li S - is an integer + * \li U - is a filename. + * \li T - is an integer + * \li A - is an integer greater than zero + * \li Q - is the sort index type for the input file. It can be "name" or + * "creation_order" (default) + * \li Z - is the sort order type for the input file. It can be "descending" or + * "ascending" (default) + * \li B - is the user block size, any value that is 512 or greater and is + * a power of 2 (1024 default) + * \li F - is the shared object header message type, any of . If F is not specified, S applies to all messages + * + * \subsubsection subsubsec_cltools_h5repack_options_bound Library Version Bounds + * BOUND is an integer indicating the library release versions to use when + * creating objects in the file (see #H5Pset_libver_bounds()): + * \li 0 This is #H5F_LIBVER_EARLIEST in #H5F_libver_t struct + * \li 1 This is #H5F_LIBVER_V18 in #H5F_libver_t struct + * \li 2 This is #H5F_LIBVER_V110 in #H5F_libver_t struct + * \li 3 This is #H5F_LIBVER_V112 in #H5F_libver_t struct + * \li 4 This is #H5F_LIBVER_V114 in #H5F_libver_t struct + * \li 5 This is #H5F_LIBVER_V116 in #H5F_libver_t struct + * \li #H5F_LIBVER_LATEST is aliased to #H5F_LIBVER_V116 for this release + * + * \subsubsection subsubsec_cltools_h5repack_options_fs File Strategy Settings + * FS_STRATEGY is a string indicating the file space strategy used: + * \li FSM_AGGR + * The mechanisms used in managing file space are free-space + * managers, aggregators and virtual file driver. + * \li PAGE + * The mechanisms used in managing file space are free-space + * managers with embedded paged aggregation and virtual file driver. + * \li AGGR + * The mechanisms used in managing file space are aggregators and + * virtual file driver. + * \li NONE + * The mechanisms used in managing file space are virtual file + * driver. + * \li The default strategy when not set is \b FSM_AGGR without persisting free-space. + * + * \li FS_PERSIST is 1 for persisting free-space or 0 for not persisting free-space. + * The default when not set is not persisting free-space. + * The value is ignored for \b AGGR and \b NONE strategies. + * + * \li FS_THRESHOLD is the minimum size (in bytes) of free-space sections to be + * tracked by the library. The default when not set is 1. + * The value is ignored for \b AGGR and \b NONE strategies. + * + * \li FS_PAGESIZE is the size (in bytes) >=512 that is used by the library when + * the file space strategy \b PAGE is used. + * The default when not set is 4096. + * + * \subsubsection subsubsec_cltools_h5repack_options_filt Applying a Third-party Filter + * FILT - is a string with the format: + * + * \li \:\=\ + * + * \li \ is a comma separated list of object names, meaning apply + * compression only to those objects. If no names are specified, the filter + * is applied to all objects + * \li \ can be: + *
  • GZIP to apply the HDF5 GZIP filter (GZIP compression)
    • + *
  • SZIP to apply the HDF5 SZIP filter (SZIP compression)
    • + *
  • SHUF to apply the HDF5 shuffle filter
    • + *
  • FLET to apply the HDF5 checksum filter
    • + *
  • NBIT to apply the HDF5 NBIT filter (NBIT compression)
    • + *
  • SOFF to apply the HDF5 Scale/Offset filter
    • + *
  • UD to apply a user defined filter
    • + *
  • NONE to remove all filters
+ * \li \ is optional filter parameter information + *
  • GZIP=\ from 1-9
    • + *
  • SZIP= pixels per block is a even number in + * 2-32 and coding method is either EC or NN
    • + *
  • SHUF (no parameter)
    • + *
  • FLET (no parameter)
    • + *
  • NBIT (no parameter)
    • + *
  • SOFF=\ scale_factor is an integer and scale_type + * is either IN or DS
    • + *
  • UD=\ + *
    • Required values filter_number, filter_flag, cd_value_count, + * value1
    • Optional values value2 to valueN
    • filter_flag 1 + * is OPTIONAL or 0 is MANDATORY
  • NONE (no parameter)
+ * + * \subsubsection subsubsec_cltools_h5repack_options_lay Layout Settings + * LAYT - is a string with the format: + * + * \li \:\=\ + * + * \li \ is a comma separated list of object names, meaning that + * layout information is supplied for those objects. If no names are + * specified, the layout type is applied to all objects + * \li \ can be: + *
  • CHUNK to apply chunking layout
    • + *
  • COMPA to apply compact layout
    • + *
  • CONTI to apply contiguous layout
+ * \li \ is optional layout information + *
  • CHUNK=DIM[xDIM...xDIM], the chunk size of each dimension
    • + *
  • COMPA (no parameter)
    • + *
  • CONTI (no parameter)
+ * + * \subsubsection subsubsec_cltools_h5repack_options_note NOTE + * The environment variable H5TOOLS_BUFSIZE can be set to + * the number of MBs to change the default hyperslab buffer size from 32MB. + * \code setenv H5TOOLS_BUFSIZE=64 to double the hyperslab buffer. \endcode + * + * \subsection subsec_cltools_h5repack_examples Usage Examples + * + * \li 1) h5repack --verbose --filter=GZIP=1 file1 file2 + * + * GZIP compression with level 1 to all objects + * + * \li 2) h5repack --verbose --filter=dset1:SZIP=8,NN file1 file2 + * + * SZIP compression with 8 pixels per block and NN coding method to object dset1 + * + * \li 3) h5repack --verbose --layout=dset1,dset2:CHUNK=20x10 --filter=dset3,dset4,dset5:NONE file1 file2 + * + * Chunked layout, with a layout size of 20x10, to objects dset1 and dset2 + * and remove filters to objects dset3, dset4, dset5 + * + * \li 4) h5repack --latest --compact=10 --ssize=20:dtype file1 file2 + * + * Using latest file format with maximum compact group size of 10 and + * minimum shared datatype size of 20 + * + * \li 5) h5repack --filter=SHUF --filter=GZIP=1 file1 file2 + * + * Add both filters SHUF and GZIP in this order to all datasets + * + * \li 6) h5repack --filter=UD=307,0,1,9 file1 file2 + * + * Add bzip2 filter to all datasets + * + * \li 7) h5repack --low=0 --high=1 file1 file2 + * + * Set low=H5F_LIBVER_EARLIEST and high=H5F_LIBVER_V18 via + * H5Pset_libver_bounds() when creating the repacked file, file2 + * + * + */ + #include "H5private.h" #include "hdf5.h" #include "h5trav.h" diff --git a/tools/src/h5stat/h5stat.h b/tools/src/h5stat/h5stat.h new file mode 100644 index 00000000000..848480eb2b3 --- /dev/null +++ b/tools/src/h5stat/h5stat.h @@ -0,0 +1,65 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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 COPYING 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. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5STAT_H +#define H5STAT_H + +/** \page H5TOOL_ST_UG The HDF5 h5stat Tool + * + * \section sec_cltools_h5stat h5stat + * + * \subsection subsec_cltools_h5stat_intro Introduction + * With h5stat, you can dump stats from an HDF5 file. + * + * \subsection subsec_cltools_h5stat_usage Usage + *

h5stat [OPTIONS] file

+ * + * \subsection subsec_cltools_h5stat_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors, --enable-error-stack=2. + * + * \subsection subsec_cltools_h5stat_options Options + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * \li --file Print file information + * \li --filemetadata Print file space information for file's metadata + * \li --group Print group information + * \li --links=N Set the threshold for the # of links when printing + * information for small groups. N is an integer greater + * than 0. The default threshold is 10. + * \li --groupmetadata Print file space information for groups' metadata + * \li --dset Print dataset information + * \li --dims=N Set the threshold for the dimension sizes when printing + * information for small datasets. N is an integer greater + * than 0. The default threshold is 10. + * \li --dsetmetadata Print file space information for datasets' metadata + * \li --dtypemetadata Print datasets' datatype information + * \li --attribute Print attribute information + * \li --numattrs=N Set the threshold for the number of attributes when printing + * information for small number of attributes. N is an integer greater + * than 0. The default threshold is 10. + * \li --freespace Print free space information + * \li --summary Print summary of file space information + * \li --page-buffer-size=N Set the page buffer cache size, N=non-negative integers + * \li --s3-cred=C Supply S3 authentication information to "ros3" vfd. + * Accepts tuple of \code (\,\,\) \endcode. + * If absent or C = \code (,,) \endcode defaults to no-authentication. + * Has no effect if vfd flag not set to "ros3". + * \li --hdfs-attrs=A Supply configuration information to Hadoop VFD. + * Accepts tuple of \code (\,\, + * ...\,\,\) \endcode + * If absent or A == \code (,,,,) \endcode all default values are used. + * Has no effect if vfd flag is not 'hdfs'.
+ * If an attribute is empty, a default value will be used. + * + */ + +#endif /* H5STAT_H */ diff --git a/tools/src/misc/h5clear.h b/tools/src/misc/h5clear.h new file mode 100644 index 00000000000..354b2f6ef33 --- /dev/null +++ b/tools/src/misc/h5clear.h @@ -0,0 +1,67 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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 COPYING 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. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5CLEAR_H +#define H5CLEAR_H + +/** \page H5TOOL_CR_UG The HDF5 h5clear Tool + * + * \section sec_cltools_h5clear h5clear + * + * \subsection subsec_cltools_h5clear_intro Introduction + * With h5clear, you can clear the superblock status flag field, remove the metadata cache image, print + * the EOA and EOF, or set the EOA of a file. It is not a general repair tool and should not + * be used to fix file corruption. If a process doesn't shut down cleanly, the + * superblock mark can be left that prevents opening a file without SWMR. Then, + * h5clear can be used to remove this superblock mark so that the file can be inspected + * and appropriate actions can be taken. + * + * \subsection subsec_cltools_h5clear_usage Usage + *

h5clear [OPTIONS] file_name

+ * + * \subsection subsec_cltools_h5clear_error Error Report Option + * \li --enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors, --enable-error-stack=2. + * + * \subsection subsec_cltools_h5clear_options Options + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * \li --status Clear the status_flags field in the file's superblock + * \li --image Remove the metadata cache image from the file + * \li --filesize Print the file's EOA and EOF + * \li --increment=C Set the file's EOA to the maximum of (EOA, EOF) + C for + * the file \. + * C is >= 0; C is optional and will default to 1M when not set. + * This option helps to repair a crashed SWMR file when the stored + * EOA in the superblock is different from the actual EOF. + * The file's EOA and EOF will be the same after applying + * this option to the file. + * + * \subsection subsec_cltools_h5clear_examples Usage Examples + * \li 1) h5clear -s file_name + * + * Clear the status_flags field in the superblock of the HDF5 file . + * + * \li 2) h5clear -m file_name + * + * Remove the metadata cache image from the HDF5 file . + * + * \li 3) h5clear --increment file_name + * + * Set the EOA to the maximum of (EOA, EOF) + 1M for the file . + * + * \li 4) h5clear --increment=512 file_name + * + * Set the EOA to the maximum of (EOA, EOF) + 512 for the file\. + * + */ + +#endif /* H5CLEAR_H */ diff --git a/tools/src/misc/h5debug.h b/tools/src/misc/h5debug.h new file mode 100644 index 00000000000..e946681a6a9 --- /dev/null +++ b/tools/src/misc/h5debug.h @@ -0,0 +1,31 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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 COPYING 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. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5DEBUG_H +#define H5DEBUG_H + +/** \page H5TOOL_DG_UG The HDF5 h5debug Tool + * + * \section sec_cltools_h5debug h5debug + * + * \subsection subsec_cltools_h5debug_intro Introduction + * With h5debug, you can debug an existing HDF5 file at a low level. + * + * \subsection subsec_cltools_h5debug_usage Usage + *

h5debug filename [signature-addr [extra]*]

+ * + * \subsection subsec_cltools_h5debug_options Options + * \li signature-addr Primary data structure to dump + * \li extra Extra arguments for primary data structure + * + */ + +#endif /* H5DEBUG_H */ diff --git a/tools/src/misc/h5delete.h b/tools/src/misc/h5delete.h new file mode 100644 index 00000000000..5faedc023a4 --- /dev/null +++ b/tools/src/misc/h5delete.h @@ -0,0 +1,30 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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 COPYING 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. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5DELETE_H +#define H5DELETE_H + +/** \page H5TOOL_DT_UG The HDF5 h5delete Tool + * + * \section sec_cltools_h5delete h5delete + * + * \subsection subsec_cltools_h5delete_intro Introduction + * With h5delete, you can delete an HDF5 file. + * + * \subsection subsec_cltools_h5delete_usage Usage + *

h5delete [-f] \

+ * + * \subsection subsec_cltools_h5delete_options Options + * \li -f Suppress output + * + */ + +#endif /* H5DELETE_H */ diff --git a/tools/src/misc/h5mkgrp.h b/tools/src/misc/h5mkgrp.h new file mode 100644 index 00000000000..cb0b2740bcb --- /dev/null +++ b/tools/src/misc/h5mkgrp.h @@ -0,0 +1,53 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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 COPYING 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. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5MKGRP_H +#define H5MKGRP_H + +/** \page H5TOOL_MG_UG The HDF5 h5mkgrp Tool + * + * \section sec_cltools_h5mkgrp h5mkgrp + * + * \subsection subsec_cltools_h5mkgrp_intro Introduction + * With h5mkgrp, you can create group(s) in an HDF5 file + * + * \subsection subsec_cltools_h5mkgrp_usage Usage + *

h5mkgrp [OPTIONS] FILE GROUP

+ * + * \subsection subsec_cltools_h5mkgrp_error Error Report Option + * \li--enable-error-stack Prints messages from the HDF5 error stack as they occur. + * Optional value 2 also prints file open errors, --enable-error-stack=2. + * + * \subsection subsec_cltools_h5mkgrp_options Options + * \li --help Print a usage message and exit + * \li --version Print the library version number and exit + * \li --verbose Print information about OBJECTS and OPTIONS + * \li --latest Use latest version of file format to create groups + * \li --parents No error if existing, make parent groups as needed + * \li --vol-value Value (ID) of the VOL connector to use for opening the + * HDF5 file specified + * \li --vol-name Name of the VOL connector to use for opening the + * HDF5 file specified + * \li --vol-info VOL-specific info to pass to the VOL connector used for + * opening the HDF5 file specified.
+ * If none of the above options are used to specify a VOL, then + * the VOL named by HDF5_VOL_CONNECTOR (or the native VOL connector, + * if that environment variable is unset) will be used + * \li --vfd-value Value (ID) of the VFL driver to use for opening the + * HDF5 file specified + * \li --vfd-name Name of the VFL driver to use for opening the + * HDF5 file specified + * \li --vfd-info VFD-specific info to pass to the VFL driver used for + * opening the HDF5 file specified + * + */ + +#endif /* H5MKGRP_H */ diff --git a/tools/src/misc/h5repart.h b/tools/src/misc/h5repart.h new file mode 100644 index 00000000000..9452bd5b6f4 --- /dev/null +++ b/tools/src/misc/h5repart.h @@ -0,0 +1,47 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * 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 COPYING 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. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +#ifndef H5REPART_H +#define H5REPART_H + +/** \page H5TOOL_RT_UG The HDF5 h5repart Tool + * + * \section sec_cltools_h5repart h5repart + * + * \subsection subsec_cltools_h5repart_intro Introduction + * With h5repart, you can repartition a file family. This program can be used to + * split a single file into a family of files, join a family of + * files into a single file, or copy one family to another while + * changing the size of the family members. It can also be used + * to copy a single file to a single file with holes. + * + * \subsection subsec_cltools_h5repart_usage Usage + *

h5repart [OPTIONS] SRC DST

+ * + * \subsection subsec_cltools_h5repart_objs SRC/DST + * \li SRC The name of the source file + * \li DST The name of the destination files + * + * \subsection subsec_cltools_h5repart_options Options + * \li -v Produce verbose output + * \li -V Print version number and exit + * \li -b N The I/O block size, defaults to 1kB + * \li -m N The destination member size or 1GB + * \li -family_to_sec2 Deprecated version of -family_to_single (below) + * \li -family_to_single Change file driver from family to the default single-file + * VFD (windows or sec2) + * + * Sizes may be suffixed with 'g' for GB, 'm' for MB or 'k' for kB. + * File family names include an integer printf format such as '%%d' + * + */ + +#endif /* H5REPART_H */ diff --git a/tools/test/h5copy/CMakeTests.cmake b/tools/test/h5copy/CMakeTests.cmake index 0069eaf6aea..d4315ef134d 100644 --- a/tools/test/h5copy/CMakeTests.cmake +++ b/tools/test/h5copy/CMakeTests.cmake @@ -549,7 +549,7 @@ ADD_H5_TEST2 (grp_dsets_rename 2 ${HDF_FILE1}.h5 grp_dsets grp_rename -v -s grp_dsets -d /grp_rename/grp_dsets) endif () - # "Test copying objects into group hier. that doesn't exist yet in destination file" + # "Test copying objects into group that doesn't exist yet in destination file" ADD_H5_TEST (A_B1_simple 0 ${HDF_FILE1}.h5 -vp -s simple -d /A/B1/simple) ADD_H5_TEST (A_B2_simple2 0 ${HDF_FILE1}.h5 -vp -s simple -d /A/B2/simple2) ADD_H5_TEST (C_D_simple 0 ${HDF_FILE1}.h5 -vp -s /grp_dsets/simple -d /C/D/simple) From 6fa09bdb154ae9a5a7717124a21cc3dedbd46964 Mon Sep 17 00:00:00 2001 From: Allen Byrne <50328838+byrnHDF@users.noreply.github.com> Date: Mon, 15 Jul 2024 10:16:16 -0500 Subject: [PATCH 04/20] Add h5* compiler wrapper testing for CMake #4605 (#4613) * Add show option * remove non-static libs and correct names of static libs * Fixup the pkg-config libs and comp builds * Fix commands and add fortran pkg-config test scripts * Add help usage option --- HDF5Examples/C/H5D/test-pc.sh | 221 +++++++++++++++++++++++ HDF5Examples/C/H5G/test-pc.sh | 235 +++++++++++++++++++++++++ HDF5Examples/C/H5T/test-pc.sh | 250 ++++++++++++++++++++++++++ HDF5Examples/C/H5VDS/test-pc.sh | 133 ++++++++++++++ HDF5Examples/FORTRAN/H5D/test-pc.sh | 251 ++++++++++++++++++++++++++ HDF5Examples/FORTRAN/H5D/test.sh.in | 2 +- HDF5Examples/FORTRAN/H5G/test-pc.sh | 151 ++++++++++++++++ HDF5Examples/FORTRAN/H5T/test-pc.sh | 264 ++++++++++++++++++++++++++++ config/cmake/LIBAEC/CMakeLists.txt | 127 ++++++------- config/cmake/ZLIB/CMakeLists.txt | 203 ++++++++++++--------- config/cmake/ZLIBNG/CMakeLists.txt | 16 +- config/cmake/libh5cc.in | 42 ++++- src/CMakeLists.txt | 15 +- 13 files changed, 1731 insertions(+), 179 deletions(-) create mode 100755 HDF5Examples/C/H5D/test-pc.sh create mode 100755 HDF5Examples/C/H5G/test-pc.sh create mode 100755 HDF5Examples/C/H5T/test-pc.sh create mode 100644 HDF5Examples/C/H5VDS/test-pc.sh create mode 100755 HDF5Examples/FORTRAN/H5D/test-pc.sh create mode 100755 HDF5Examples/FORTRAN/H5G/test-pc.sh create mode 100755 HDF5Examples/FORTRAN/H5T/test-pc.sh diff --git a/HDF5Examples/C/H5D/test-pc.sh b/HDF5Examples/C/H5D/test-pc.sh new file mode 100755 index 00000000000..e0cda25152a --- /dev/null +++ b/HDF5Examples/C/H5D/test-pc.sh @@ -0,0 +1,221 @@ +#! /bin/sh +# +# 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 COPYING 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 is for use of h5cc created with the CMake process +# HDF5_HOME is expected to be set + +srcdir=.. +builddir=. +verbose=yes +nerrors=0 + +# HDF5 compile commands, assuming they are in your $PATH. +H5CC=$HDF5_HOME/bin/h5cc +LD_LIBRARY_PATH=$HDF5_HOME/lib +export LD_LIBRARY_PATH + +if ! test -f $H5CC; then + echo "Set paths for H5CC and LD_LIBRARY_PATH in test.sh" + echo "Set environment variable HDF5_HOME to the hdf5 install dir" + echo "h5cc was not found at $H5CC" + exit $EXIT_FAILURE +fi + +H5DUMP=`echo $H5CC | sed -e 's/\/[^/]*$/\/h5dump/'`; +H5_LIBVER=$($H5CC -showconfig | grep -i "HDF5 Version:" | sed 's/^.* //g' | sed 's/[-].*//g') +H5_APIVER=$($H5CC -showconfig | grep -i "Default API mapping:" | sed 's/^.* //g' | sed 's/v//g' | sed 's/1/1_/') + +H5_MAJORVER=$(echo $H5_LIBVER | cut -f1 -d'.' | sed -E 's/\./_/g') +H5_MINORVER=$(echo $H5_LIBVER | cut -f2 -d'.' | sed -E 's/\./_/g') +H5_RELEASEVER=$(echo $H5_LIBVER | cut -f3 -d'.' | sed -E 's/\./_/g') +H5_LIBVER_DIR=$H5_MAJORVER$H5_MINORVER + +# Shell commands used in Makefiles +RM="rm -rf" +DIFF="diff -c" +CMP="cmp -s" +GREP='grep' +CP="cp -p" # Use -p to preserve mode,ownership,timestamps +DIRNAME='dirname' +LS='ls' +AWK='awk' + +# setup plugin path +ENVCMD="env HDF5_PLUGIN_PATH=$LD_LIBRARY_PATH/plugin" + +TESTDIR=$builddir + + +case `echo "testing\c"; echo 1,2,3`,`echo -n testing; echo 1,2,3` in + *c*,-n*) ECHO_N= ECHO_C=' +' ;; + *c*,* ) ECHO_N=-n ECHO_C= ;; + *) ECHO_N= ECHO_C='\c' ;; +esac +ECHO_N="echo $ECHO_N" + + +exout() { + $* +} + +dumpout() { + $H5DUMP $* +} + +# compare current version, required version. +# returns if cur_ver < req_ver is true. +version_compare() { + version_lt=0 + if [ ! "$(printf '%s\n' "$1" "$2" | sort -V | head -n1)" = "$2" ]; then + version_lt=1 + fi +} + + +topics="alloc checksum chunk compact extern fillval gzip hyper \ +rdwr shuffle szip unlimadd unlimgzip unlimmod" +topics18="" + +version_compare "$H5_LIBVER" "1.8.0" +# check if HDF5 version is < 1.8.0 +if [ "$version_lt" = 1 ]; then + dir16="/16" +else + dir16="" + topics18="nbit sofloat soint transform" +fi + +return_val=0 + +#Remove external data file from h5ex_d_extern +rm -f h5ex_d_extern.data + +for topic in $topics +do + $H5CC $srcdir/h5ex_d_$topic.c -o h5ex_d_$topic +done + +for topic in $topics +do + fname=h5ex_d_$topic + $ECHO_N "Testing C/H5D/$fname...$ECHO_C" + exout .$dir16/$fname >tmp.test + status=$? + if test $status -eq 1 + then + echo " Unsupported feature" + status=0 + else + cmp -s tmp.test $srcdir/tfiles/16/$fname.tst + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + dumpout $fname.h5 >tmp.test + rm -f $fname.h5 + cmp -s tmp.test $srcdir/tfiles/16/$fname.ddl + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + echo " Passed" + fi + fi + return_val=`expr $status + $return_val` + fi +done + +#######Non-standard tests####### +USE_ALT="" +### Set default tfiles directory for tests +nbitdir="18" +version_compare "$H5_LIBVER" "1.8.23" +# check if HDF5 version is < 1.8.23 +if [ "$version_lt" = 1 ]; then + USE_ALT="22" +else +# check if HDF5 version is >= 1.10.0 and < 1.10.8 + version_compare "$H5_LIBVER" "1.10.0" + if [ "$version_lt" = 0 ]; then + version_compare "$H5_LIBVER" "1.10.8" + if [ "$version_lt" = 1 ]; then + USE_ALT="07" + nbitdir="110" + fi + fi +fi + +for topic in $topics18 +do + $H5CC $srcdir/h5ex_d_$topic.c -o h5ex_d_$topic +done + +for topic in $topics18 +do + fname=h5ex_d_$topic + $ECHO_N "Testing C/H5D/$fname...$ECHO_C" + exout ./$fname >tmp.test + status=$? + if test $status -eq 1 + then + echo " Unsupported feature" + status=0 + else + if [[ $fname == "h5ex_d_nbit" ]] + then + tdir=$nbitdir + if [[ $USE_ALT == "" ]] + then + ### set USE_ALT=07 if not set above + USE_ALT="07" + fi + else + tdir=18 + ### unset USE_ALT for the other topics + USE_ALT="" + fi + cmp -s tmp.test $srcdir/tfiles/18/$fname.tst + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + if [[ $fname == "h5ex_d_transform" ]] + then + targ="-n" + else + targ="" + fi + dumpout $targ $fname.h5 >tmp.test + rm -f $fname.h5 + cmp -s tmp.test $srcdir/tfiles/$tdir/$fname$USE_ALT.ddl + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + echo " Passed" + fi + fi + return_val=`expr $status + $return_val` + fi +done + + +#Remove external data file from h5ex_d_extern +rm -f h5ex_d_extern.data +rm -f tmp.test +echo "$return_val tests failed in C/H5D/" +exit $return_val diff --git a/HDF5Examples/C/H5G/test-pc.sh b/HDF5Examples/C/H5G/test-pc.sh new file mode 100755 index 00000000000..4c996a45a58 --- /dev/null +++ b/HDF5Examples/C/H5G/test-pc.sh @@ -0,0 +1,235 @@ +#! /bin/sh +# +# Copyright by The HDF Group. +# Copyright by the Board of Trustees of the University of Illinois. +# 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 COPYING 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 is for use of h5cc created with the CMake process +# HDF5_HOME is expected to be set + +srcdir=.. +builddir=. +verbose=yes +nerrors=0 + +# HDF5 compile commands, assuming they are in your $PATH. +H5CC=$HDF5_HOME/bin/h5cc +LD_LIBRARY_PATH=$HDF5_HOME/lib +export LD_LIBRARY_PATH + +if ! test -f $H5CC; then + echo "Set paths for H5CC and LD_LIBRARY_PATH in test.sh" + echo "Set environment variable HDF5_HOME to the hdf5 install dir" + echo "h5cc was not found at $H5CC" + exit $EXIT_FAILURE +fi + +H5DUMP=`echo $H5CC | sed -e 's/\/[^/]*$/\/h5dump/'`; +H5_LIBVER=$($H5CC -showconfig | grep -i "HDF5 Version:" | sed 's/^.* //g' | sed 's/[-].*//g') +H5_APIVER=$($H5CC -showconfig | grep -i "Default API mapping:" | sed 's/^.* //g' | sed 's/v//g' | sed 's/1/1_/') + +H5_MAJORVER=$(echo $H5_LIBVER | cut -f1 -d'.' | sed -E 's/\./_/g') +H5_MINORVER=$(echo $H5_LIBVER | cut -f2 -d'.' | sed -E 's/\./_/g') +H5_RELEASEVER=$(echo $H5_LIBVER | cut -f3 -d'.' | sed -E 's/\./_/g') +H5_LIBVER_DIR=$H5_MAJORVER$H5_MINORVER + +# Shell commands used in Makefiles +RM="rm -rf" +DIFF="diff -c" +CMP="cmp -s" +GREP='grep' +CP="cp -p" # Use -p to preserve mode,ownership,timestamps +DIRNAME='dirname' +LS='ls' +AWK='awk' + +# setup plugin path +ENVCMD="env HDF5_PLUGIN_PATH=$LD_LIBRARY_PATH/plugin" + +TESTDIR=$builddir + + +case `echo "testing\c"; echo 1,2,3`,`echo -n testing; echo 1,2,3` in + *c*,-n*) ECHO_N= ECHO_C=' +' ;; + *c*,* ) ECHO_N=-n ECHO_C= ;; + *) ECHO_N= ECHO_C='\c' ;; +esac +ECHO_N="echo $ECHO_N" + + +exout() { + $* +} + +dumpout() { + $H5DUMP $* +} + +$H5CC $srcdir/h5ex_g_create.c -o h5ex_g_create + +$ECHO_N "Testing C/H5G/h5ex_g_create...$ECHO_C" +./h5ex_g_create +dumpout h5ex_g_create.h5 >tmp.test +rm -f h5ex_g_create.h5 +cmp -s tmp.test $srcdir/tfiles/16/h5ex_g_create.ddl +status=$? +if test $status -ne 0 +then + echo " FAILED!" +else + echo " Passed" +fi +return_val=`expr $status + $return_val` + +$H5CC $srcdir/h5ex_g_iterate.c -o h5ex_g_iterate + +$ECHO_N "Testing C/H5G/h5ex_g_iterate...$ECHO_C" +if test -f h5ex_g_iterate.h5 +then + exout ./h5ex_g_iterate >tmp.test +else + cp $srcdir/h5ex_g_iterate.h5 h5ex_g_iterate.h5 + exout ./h5ex_g_iterate >tmp.test + rm -f h5ex_g_iterate.h5 +fi +cmp -s tmp.test $srcdir/tfiles/16/h5ex_g_iterate.tst +status=$? +if test $status -ne 0 +then + echo " FAILED!" +else + echo " Passed" +fi +return_val=`expr $status + $return_val` + +$H5CC $srcdir/h5ex_g_traverse.c -o h5ex_g_traverse + +$ECHO_N "Testing C/H5G/h5ex_g_traverse...$ECHO_C" +if test -f h5ex_g_traverse.h5 +then + exout ./h5ex_g_traverse >tmp.test +else + cp $srcdir/h5ex_g_traverse.h5 h5ex_g_traverse.h5 + exout ./h5ex_g_traverse >tmp.test + rm -f h5ex_g_traverse.h5 +fi +cmp -s tmp.test $srcdir/tfiles/16/h5ex_g_traverse.tst +status=$? +if test $status -ne 0 +then + echo " FAILED!" +else + echo " Passed" +fi +return_val=`expr $status + $return_val` + +$H5CC $srcdir/h5ex_g_visit.c -o h5ex_g_visit + +$ECHO_N "Testing C/H5G/h5ex_g_visit...$ECHO_C" +if test -f h5ex_g_visit.h5 +then + exout ./h5ex_g_visit >tmp.test +else + cp $srcdir/h5ex_g_visit.h5 h5ex_g_visit.h5 + exout ./h5ex_g_visit >tmp.test + rm -f h5ex_g_visit.h5 +fi +cmp -s tmp.test $srcdir/tfiles/18/h5ex_g_visit.tst +status=$? +if test $status -ne 0 +then + echo " FAILED!" +else + echo " Passed" +fi +return_val=`expr $status + $return_val` + +$H5CC $srcdir/h5ex_g_compact.c -o h5ex_g_compact + +$ECHO_N "Testing C/H5G/h5ex_g_compact...$ECHO_C" +exout ./h5ex_g_compact >tmp.test +cmp -s tmp.test $srcdir/tfiles/18/h5ex_g_compact.tst +status=$? +if test $status -ne 0 +then + echo " FAILED!" +else + dumpout h5ex_g_compact1.h5 >tmp.test + cmp -s tmp.test $srcdir/tfiles/18/h5ex_g_compact1.ddl + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + dumpout h5ex_g_compact2.h5 >tmp.test + cmp -s tmp.test $srcdir/tfiles/18/h5ex_g_compact2.ddl + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + echo " Passed" + fi + fi +fi +return_val=`expr $status + $return_val` +rm -f h5ex_g_compact1.h5 +rm -f h5ex_g_compact2.h5 + +$H5CC $srcdir/h5ex_g_phase.c -o h5ex_g_phase + +$ECHO_N "Testing C/H5G/h5ex_g_phase...$ECHO_C" +exout ./h5ex_g_phase >tmp.test +cmp -s tmp.test $srcdir/tfiles/18/h5ex_g_phase.tst +status=$? +if test $status -ne 0 +then + echo " FAILED!" +else + echo " Passed" +fi +return_val=`expr $status + $return_val` +rm -f h5ex_g_phase.h5 + +$H5CC $srcdir/h5ex_g_corder.c -o h5ex_g_corder + +$ECHO_N "Testing C/H5G/h5ex_g_corder...$ECHO_C" +exout ./h5ex_g_corder >tmp.test +cmp -s tmp.test $srcdir/tfiles/18/h5ex_g_corder.tst +status=$? +if test $status -ne 0 +then + echo " FAILED!" +else + echo " Passed" +fi +return_val=`expr $status + $return_val` +rm -f h5ex_g_corder.h5 + +$H5CC $srcdir/h5ex_g_intermediate.c -o h5ex_g_intermediate + +$ECHO_N "Testing C/H5G/h5ex_g_intermediate...$ECHO_C" +exout ./h5ex_g_intermediate >tmp.test +cmp -s tmp.test $srcdir/tfiles/18/h5ex_g_intermediate.tst +status=$? +if test $status -ne 0 +then + echo " FAILED!" +else + echo " Passed" +fi +return_val=`expr $status + $return_val` +rm -f h5ex_g_intermediate.h5 + + +rm -f tmp.test +echo "$return_val tests failed in C/H5G/" +exit $return_val diff --git a/HDF5Examples/C/H5T/test-pc.sh b/HDF5Examples/C/H5T/test-pc.sh new file mode 100755 index 00000000000..5a773f6097b --- /dev/null +++ b/HDF5Examples/C/H5T/test-pc.sh @@ -0,0 +1,250 @@ +#! /bin/sh +# +# Copyright by The HDF Group. +# Copyright by the Board of Trustees of the University of Illinois. +# 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 COPYING 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 is for use of h5cc created with the CMake process +# HDF5_HOME is expected to be set + +srcdir=.. +builddir=. +verbose=yes +nerrors=0 + +# HDF5 compile commands, assuming they are in your $PATH. +H5CC=$HDF5_HOME/bin/h5cc +LD_LIBRARY_PATH=$HDF5_HOME/lib +export LD_LIBRARY_PATH + +if ! test -f $H5CC; then + echo "Set paths for H5CC and LD_LIBRARY_PATH in test.sh" + echo "Set environment variable HDF5_HOME to the hdf5 install dir" + echo "h5cc was not found at $H5CC" + exit $EXIT_FAILURE +fi + +H5DUMP=`echo $H5CC | sed -e 's/\/[^/]*$/\/h5dump/'`; +H5_LIBVER=$($H5CC -showconfig | grep -i "HDF5 Version:" | sed 's/^.* //g' | sed 's/[-].*//g') +H5_APIVER=$($H5CC -showconfig | grep -i "Default API mapping:" | sed 's/^.* //g' | sed 's/v//g' | sed 's/1/1_/') + +H5_MAJORVER=$(echo $H5_LIBVER | cut -f1 -d'.' | sed -E 's/\./_/g') +H5_MINORVER=$(echo $H5_LIBVER | cut -f2 -d'.' | sed -E 's/\./_/g') +H5_RELEASEVER=$(echo $H5_LIBVER | cut -f3 -d'.' | sed -E 's/\./_/g') +H5_LIBVER_DIR=$H5_MAJORVER$H5_MINORVER + +# Shell commands used in Makefiles +RM="rm -rf" +DIFF="diff -c" +CMP="cmp -s" +GREP='grep' +CP="cp -p" # Use -p to preserve mode,ownership,timestamps +DIRNAME='dirname' +LS='ls' +AWK='awk' + +# setup plugin path +ENVCMD="env HDF5_PLUGIN_PATH=$LD_LIBRARY_PATH/plugin" + +TESTDIR=$builddir + + +case `echo "testing\c"; echo 1,2,3`,`echo -n testing; echo 1,2,3` in + *c*,-n*) ECHO_N= ECHO_C=' +' ;; + *c*,* ) ECHO_N=-n ECHO_C= ;; + *) ECHO_N= ECHO_C='\c' ;; +esac +ECHO_N="echo $ECHO_N" + + +exout() { + $* +} + +dumpout() { + $H5DUMP $* +} + +# compare current version, required version. +# returns if cur_ver < req_ver is true. +version_compare() { + version_lt=0 + if [ ! "$(printf '%s\n' "$1" "$2" | sort -V | head -n1)" = "$2" ]; then + version_lt=1 + fi +} + + +topics="array arrayatt bit bitatt cmpd cmpdatt cpxcmpd cpxcmpdatt enum enumatt float floatatt \ +int intatt opaque opaqueatt string stringatt vlstring vlstringatt \ +commit" + +return_val=0 + +for topic in $topics +do + $H5CC $srcdir/h5ex_t_$topic.c -o h5ex_t_$topic +done + +for topic in $topics +do + fname=h5ex_t_$topic + $ECHO_N "Testing C/H5T/$fname...$ECHO_C" + exout ./$fname >tmp.test + cmp -s tmp.test $srcdir/tfiles/16/$fname.tst + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + if [[ $fname == "h5ex_t_cpxcmpd" || $fname == "h5ex_t_cpxcmpdatt" ]] + then + targ="-n" + else + targ="" + fi + dumpout $targ $fname.h5 >tmp.test + rm -f $fname.h5 + cmp -s tmp.test $srcdir/tfiles/18/$fname.ddl + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + echo " Passed" + fi + fi + return_val=`expr $status + $return_val` +done + + +#######Non-standard tests####### + +USE_ALT="" +if [ "$H5_LIBVER_DIR" = "110" ]; then + # check if HDF5 version is < 1.10.7 + version_compare "$H5_LIBVER" "1.10.7" + if [ "$version_lt" = 1 ]; then + USE_ALT="06" + fi +else + if [ "$H5_LIBVER_DIR" = "18" ]; then + # check if HDF5 version is < 1.8.22 + version_compare "$H5_LIBVER" "1.8.22" + if [ "$version_lt" = 1 ]; then + USE_ALT="21" + fi + fi +fi + +topics="objref objrefatt regref regrefatt" + +for topic in $topics +do + $H5CC $srcdir/h5ex_t_$topic.c -o h5ex_t_$topic +done + +for topic in $topics +do + fname=h5ex_t_$topic + $ECHO_N "Testing C/H5T/$fname...$ECHO_C" + exout ./$fname >tmp.test + cmp -s tmp.test $srcdir/tfiles/16/$fname.tst + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + dumpout $fname.h5 >tmp.test + rm -f $fname.h5 + version_compare "$H5_LIBVER" "1.10.0" + if [ "$version_lt" = 1 ]; then + cmp -s tmp.test $srcdir/tfiles/18/$fname$USE_ALT.ddl + else + version_compare "$H5_LIBVER" "1.12.0" + if [ "$version_lt" = 1 ]; then + version_compare "$H5_LIBVER" "1.10.7" + if [ "$version_lt" = 1 ]; then + cmp -s tmp.test $srcdir/tfiles/110/$fname$USE_ALT.ddl + else + cmp -s tmp.test $srcdir/tfiles/18/$fname.ddl + fi + else + cmp -s tmp.test $srcdir/tfiles/112/$fname.ddl + fi + fi + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + echo " Passed" + fi + fi + return_val=`expr $status + $return_val` +done + +topics="vlen vlenatt" + +for topic in $topics +do + $H5CC $srcdir/h5ex_t_$topic.c -o h5ex_t_$topic +done + +for topic in $topics +do + fname=h5ex_t_$topic + $ECHO_N "Testing C/H5T/$fname...$ECHO_C" + exout ./$fname >tmp.test + cmp -s tmp.test $srcdir/tfiles/16/$fname.tst + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + dumpout $fname.h5 >tmp.test + rm -f $fname.h5 + version_compare "$H5_LIBVER" "1.14.3" + if [ "$version_lt" = 1 ]; then + cmp -s tmp.test $srcdir/tfiles/18/$fname.ddl + else + cmp -s tmp.test $srcdir/tfiles/114/$fname.ddl + fi + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + echo " Passed" + fi + fi + return_val=`expr $status + $return_val` +done + +$H5CC $srcdir/h5ex_t_convert.c -o h5ex_t_convert + +fname=h5ex_t_convert +$ECHO_N "Testing C/H5T/$fname...$ECHO_C" +exout ./$fname >tmp.test +cmp -s tmp.test $srcdir/tfiles/16/$fname.tst +status=$? +if test $status -ne 0 +then + echo " FAILED!" +else + echo " Passed" +fi +return_val=`expr $status + $return_val` + + +rm -f tmp.test +echo "$return_val tests failed in C/H5T/" +exit $return_val diff --git a/HDF5Examples/C/H5VDS/test-pc.sh b/HDF5Examples/C/H5VDS/test-pc.sh new file mode 100644 index 00000000000..e0ee85eab53 --- /dev/null +++ b/HDF5Examples/C/H5VDS/test-pc.sh @@ -0,0 +1,133 @@ +#! /bin/sh +# +# 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 COPYING 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 is for use of h5cc created with the CMake process +# HDF5_HOME is expected to be set + +srcdir=.. +builddir=. +verbose=yes +nerrors=0 + +# HDF5 compile commands, assuming they are in your $PATH. +H5CC=$HDF5_HOME/bin/h5cc +LD_LIBRARY_PATH=$HDF5_HOME/lib +export LD_LIBRARY_PATH + +if ! test -f $H5CC; then + echo "Set paths for H5CC and LD_LIBRARY_PATH in test.sh" + echo "Set environment variable HDF5_HOME to the hdf5 install dir" + echo "h5cc was not found at $H5CC" + exit $EXIT_FAILURE +fi + +H5DUMP=`echo $H5CC | sed -e 's/\/[^/]*$/\/h5dump/'`; +H5_LIBVER=$($H5CC -showconfig | grep -i "HDF5 Version:" | sed 's/^.* //g' | sed 's/[-].*//g') +H5_APIVER=$($H5CC -showconfig | grep -i "Default API mapping:" | sed 's/^.* //g' | sed 's/v//g' | sed 's/1/1_/') + +H5_MAJORVER=$(echo $H5_LIBVER | cut -f1 -d'.' | sed -E 's/\./_/g') +H5_MINORVER=$(echo $H5_LIBVER | cut -f2 -d'.' | sed -E 's/\./_/g') +H5_RELEASEVER=$(echo $H5_LIBVER | cut -f3 -d'.' | sed -E 's/\./_/g') +H5_LIBVER_DIR=$H5_MAJORVER$H5_MINORVER + +# Shell commands used in Makefiles +RM="rm -rf" +DIFF="diff -c" +CMP="cmp -s" +GREP='grep' +CP="cp -p" # Use -p to preserve mode,ownership,timestamps +DIRNAME='dirname' +LS='ls' +AWK='awk' + +# setup plugin path +ENVCMD="env HDF5_PLUGIN_PATH=$LD_LIBRARY_PATH/plugin" + +TESTDIR=$builddir + + +case `echo "testing\c"; echo 1,2,3`,`echo -n testing; echo 1,2,3` in + *c*,-n*) ECHO_N= ECHO_C=' +' ;; + *c*,* ) ECHO_N=-n ECHO_C= ;; + *) ECHO_N= ECHO_C='\c' ;; +esac +ECHO_N="echo $ECHO_N" + + +exout() { + $* +} + +dumpout() { + $H5DUMP $* +} + +# compare current version, required version. +# returns if cur_ver < req_ver is true. +version_compare() { + version_lt=0 + if [ ! "$(printf '%s\n' "$1" "$2" | sort -V | head -n1)" = "$2" ]; then + version_lt=1 + fi +} + + +topics="" +topics110="vds vds-exc vds-exclim vds-eiger vds-simpleIO vds-percival vds-percival-unlim vds-percival-unlim-maxmin" + +return_val=0 + +version_compare "$H5_LIBVER" "1.10.0" +if [ "$version_lt" = 0 ]; then + for topic in $topics110 + do + $H5CC $srcdir/h5ex_d_$topic.c -o h5ex_d_$topic + done + + for topic in $topics110 + do + fname=h5ex_$topic + $ECHO_N "Testing C/H5VDS/$fname...$ECHO_C" + exout ./$fname >tmp.test + status=$? + if test $status -eq 1 + then + echo " Unsupported feature" + status=0 + else + cmp -s tmp.test $srcdir/tfiles/110/$fname.tst + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + dumpout $fname.h5 >tmp.test + rm -f $fname.h5 + cmp -s tmp.test $srcdir/tfiles/110/$fname.ddl + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + echo " Passed" + fi + fi + return_val=`expr $status + $return_val` + fi + done +fi + + +rm -f tmp.test +echo "$return_val tests failed in C/H5VDS/" +exit $return_val diff --git a/HDF5Examples/FORTRAN/H5D/test-pc.sh b/HDF5Examples/FORTRAN/H5D/test-pc.sh new file mode 100755 index 00000000000..8d77d9782ff --- /dev/null +++ b/HDF5Examples/FORTRAN/H5D/test-pc.sh @@ -0,0 +1,251 @@ +#! /bin/sh +# +# 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 COPYING 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 is for use of h5cc created with the CMake process +# HDF5_HOME is expected to be set + +srcdir=.. +builddir=. +verbose=yes +nerrors=0 + +# HDF5 compile commands, assuming they are in your $PATH. +H5FC=$HDF5_HOME/bin/h5fc +LD_LIBRARY_PATH=$HDF5_HOME/lib +export LD_LIBRARY_PATH + +if ! test -f $H5FC; then + echo "Set paths for H5FC and LD_LIBRARY_PATH in test.sh" + echo "Set environment variable HDF5_HOME to the hdf5 install dir" + echo "h5fc was not found at $H5FC" + exit $EXIT_FAILURE +fi + +H5DUMP=`echo $H5FC | sed -e 's/\/[^/]*$/\/h5dump/'`; +H5_LIBVER=$($H5FC -showconfig | grep -i "HDF5 Version:" | sed 's/^.* //g' | sed 's/[-].*//g') +H5_APIVER=$($H5FC -showconfig | grep -i "Default API mapping:" | sed 's/^.* //g' | sed 's/v//g' | sed 's/1/1_/') + +H5_MAJORVER=$(echo $H5_LIBVER | cut -f1 -d'.' | sed -E 's/\./_/g') +H5_MINORVER=$(echo $H5_LIBVER | cut -f2 -d'.' | sed -E 's/\./_/g') +H5_RELEASEVER=$(echo $H5_LIBVER | cut -f3 -d'.' | sed -E 's/\./_/g') +H5_LIBVER_DIR=$H5_MAJORVER$H5_MINORVER + +# Shell commands used in Makefiles +RM="rm -rf" +DIFF="diff -c" +CMP="cmp -s" +GREP='grep' +CP="cp -p" # Use -p to preserve mode,ownership,timestamps +DIRNAME='dirname' +LS='ls' +AWK='awk' + +# setup plugin path +ENVCMD="env HDF5_PLUGIN_PATH=$LD_LIBRARY_PATH/plugin" + +TESTDIR=$builddir + + +case `echo "testing\c"; echo 1,2,3`,`echo -n testing; echo 1,2,3` in + *c*,-n*) ECHO_N= ECHO_C=' +' ;; + *c*,* ) ECHO_N=-n ECHO_C= ;; + *) ECHO_N= ECHO_C='\c' ;; +esac +ECHO_N="echo $ECHO_N" + + +exout() { + $* +} + +dumpout() { + $H5DUMP $* +} + +# compare current version, required version. +# returns if cur_ver < req_ver is true. +version_compare() { + version_lt=0 + if [ ! "$(printf '%s\n' "$1" "$2" | sort -V | head -n1)" = "$2" ]; then + version_lt=1 + fi +} + + +topics="alloc \ + checksum \ + chunk \ + compact \ + extern \ + fillval \ + gzip \ + hyper \ + rdwr \ + soint \ + szip \ + unlimmod" + +FORTRAN_2003_CONDITIONAL_F="@FORTRAN_2003_CONDITIONAL_F@" + +if [ "$FORTRAN_2003_CONDITIONAL_F" = "Xyes" ]; then + topics="$topics rdwr_kind" +fi + +return_val=0 + +#Remove external data file from h5ex_d_extern +rm -f h5ex_d_extern.data + +for topic in $topics +do + $H5FC $srcdir/h5ex_d_$topic.F90 -o h5ex_d_$topic +done + +for topic in $topics +do + fname=h5ex_d_$topic + $ECHO_N "Testing FORTRAN/H5D/$fname...$ECHO_C" + exout ./$fname >tmp.test + status=$? + if test $status -eq 1 + then + echo " Unsupported feature" + status=0 + else + if [ "$topic" = "alloc" ]; then + # Check if the only difference is the size of the unallocated space. This + # was fixed later in HDF5 to be of zero size. + status=0 + diff tmp.test $srcdir/tfiles/18/$fname.tst > tmp.diff + if [ $? -ne 0 ]; then + NumOfFinds=`grep -c "0 bytes" tmp.diff | wc -l` + rm -f tmp.diff + if [ "$NumOfFinds" -gt "1" ]; then + status=1 + fi + fi + else + cmp -s tmp.test $srcdir/tfiles/18/$fname.tst + status=$? + fi + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + dumpout $fname.h5 >tmp.test + rm -f $fname.h5 + cmp -s tmp.test $srcdir/tfiles/18/$fname.ddl + status=$? + if test $status -ne 0 + then + # test to see if the only difference is because of big-endian and little-endian + diff tmp.test $srcdir/tfiles/18/$fname.ddl > tmp.diff + echo " " + NumOfFinds=`grep -c "DATATYPE" tmp.diff` + NumOfFinds=`expr $NumOfFinds \* 2` + NumOfLines=`wc -l tmp.test + status=$? + if test $status -eq 1 + then + echo " Unsupported feature" + status=0 + else + if [[ $fname == "h5ex_d_nbit" ]] + then + tdir=$nbitdir + if [[ $USE_ALT == "" ]] + then + ### set USE_ALT=07 if not set above + USE_ALT="07" + fi + else + tdir=18 + ### unset USE_ALT for the other topics + USE_ALT="" + fi + cmp -s tmp.test $srcdir/tfiles/18/$fname.tst + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + if [[ $fname == "h5ex_d_transform" ]] + then + targ="-n" + else + targ="" + fi + dumpout $targ $fname.h5 >tmp.test + rm -f $fname.h5 + cmp -s tmp.test $srcdir/tfiles/$tdir/$fname$USE_ALT.ddl + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + echo " Passed" + fi + fi + return_val=`expr $status + $return_val` + fi +done + + +rm -f tmp.test +echo "$return_val tests failed in FORTRAN/H5D/" +exit $return_val diff --git a/HDF5Examples/FORTRAN/H5D/test.sh.in b/HDF5Examples/FORTRAN/H5D/test.sh.in index bdd17c283f8..e67eccd5351 100755 --- a/HDF5Examples/FORTRAN/H5D/test.sh.in +++ b/HDF5Examples/FORTRAN/H5D/test.sh.in @@ -151,7 +151,7 @@ else fi fi -topics="nbit" +topics18="nbit" for topic in $topics18 do fname=h5ex_d_$topic diff --git a/HDF5Examples/FORTRAN/H5G/test-pc.sh b/HDF5Examples/FORTRAN/H5G/test-pc.sh new file mode 100755 index 00000000000..90b02f117dd --- /dev/null +++ b/HDF5Examples/FORTRAN/H5G/test-pc.sh @@ -0,0 +1,151 @@ +#! /bin/sh +# +# Copyright by The HDF Group. +# Copyright by the Board of Trustees of the University of Illinois. +# 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 COPYING 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 is for use of h5cc created with the CMake process +# HDF5_HOME is expected to be set + +srcdir=.. +builddir=. +verbose=yes +nerrors=0 + +# HDF5 compile commands, assuming they are in your $PATH. +H5FC=$HDF5_HOME/bin/h5fc +LD_LIBRARY_PATH=$HDF5_HOME/lib +export LD_LIBRARY_PATH + +if ! test -f $H5FC; then + echo "Set paths for H5FC and LD_LIBRARY_PATH in test.sh" + echo "Set environment variable HDF5_HOME to the hdf5 install dir" + echo "h5fc was not found at $H5FC" + exit $EXIT_FAILURE +fi + +H5DUMP=`echo $H5FC | sed -e 's/\/[^/]*$/\/h5dump/'`; +H5_LIBVER=$($H5FC -showconfig | grep -i "HDF5 Version:" | sed 's/^.* //g' | sed 's/[-].*//g') +H5_APIVER=$($H5FC -showconfig | grep -i "Default API mapping:" | sed 's/^.* //g' | sed 's/v//g' | sed 's/1/1_/') + +H5_MAJORVER=$(echo $H5_LIBVER | cut -f1 -d'.' | sed -E 's/\./_/g') +H5_MINORVER=$(echo $H5_LIBVER | cut -f2 -d'.' | sed -E 's/\./_/g') +H5_RELEASEVER=$(echo $H5_LIBVER | cut -f3 -d'.' | sed -E 's/\./_/g') +H5_LIBVER_DIR=$H5_MAJORVER$H5_MINORVER + +# Shell commands used in Makefiles +RM="rm -rf" +DIFF="diff -c" +CMP="cmp -s" +GREP='grep' +CP="cp -p" # Use -p to preserve mode,ownership,timestamps +DIRNAME='dirname' +LS='ls' +AWK='awk' + +# setup plugin path +ENVCMD="env HDF5_PLUGIN_PATH=$LD_LIBRARY_PATH/plugin" + +TESTDIR=$builddir + + +case `echo "testing\c"; echo 1,2,3`,`echo -n testing; echo 1,2,3` in + *c*,-n*) ECHO_N= ECHO_C=' +' ;; + *c*,* ) ECHO_N=-n ECHO_C= ;; + *) ECHO_N= ECHO_C='\c' ;; +esac +ECHO_N="echo $ECHO_N" + + +exout() { + $* +} + +dumpout() { + $H5DUMP $* +} + +return_val=0 + + +$ECHO_N "Testing FORTRAN/H5G/h5ex_g_create...$ECHO_C" +./h5ex_g_create +dumpout h5ex_g_create.h5 >tmp.test +rm -f h5ex_g_create.h5 +cmp -s tmp.test $srcdir/tfiles/18/h5ex_g_create.ddl +status=$? +if test $status -ne 0 +then + echo " FAILED!" +else + echo " Passed" +fi +return_val=`expr $status + $return_val` + +$H5FC $srcdir/h5ex_g_compact.F90 -o h5ex_g_compact + +$ECHO_N "Testing FORTRAN/H5G/h5ex_g_compact...$ECHO_C" +./h5ex_g_compact >/dev/null +dumpout h5ex_g_compact1.h5 >tmp.test +cmp -s tmp.test $srcdir/tfiles/18/h5ex_g_compact1.ddl +status=$? +if test $status -ne 0 +then + echo " FAILED!" +else + dumpout h5ex_g_compact2.h5 >tmp.test + cmp -s tmp.test $srcdir/tfiles/18/h5ex_g_compact2.ddl + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + echo " Passed" + fi +fi +return_val=`expr $status + $return_val` +rm -f h5ex_g_compact1.h5 +rm -f h5ex_g_compact2.h5 + +$H5FC $srcdir/h5ex_g_phase.F90 -o h5ex_g_phase + +$ECHO_N "Testing FORTRAN/H5G/h5ex_g_phase...$ECHO_C" +exout ./h5ex_g_phase >tmp.test +cmp -s tmp.test $srcdir/tfiles/18/h5ex_g_phase.tst +status=$? +if test $status -ne 0 +then + echo " FAILED!" +else + echo " Passed" +fi +return_val=`expr $status + $return_val` +rm -f h5ex_g_phase.h5 + +$H5FC $srcdir/h5ex_g_corder.F90 -o h5ex_g_corder + +$ECHO_N "Testing FORTRAN/H5G/h5ex_g_corder...$ECHO_C" +exout ./h5ex_g_corder >tmp.test +cmp -s tmp.test $srcdir/tfiles/18/h5ex_g_corder.tst +status=$? +if test $status -ne 0 +then + echo " FAILED!" +else + echo " Passed" +fi +return_val=`expr $status + $return_val` +rm -f h5ex_g_corder.h5 + + +rm -f tmp.test +echo "$return_val tests failed in /FORTRAN/H5G/" +exit $return_val diff --git a/HDF5Examples/FORTRAN/H5T/test-pc.sh b/HDF5Examples/FORTRAN/H5T/test-pc.sh new file mode 100755 index 00000000000..c11fa1d8297 --- /dev/null +++ b/HDF5Examples/FORTRAN/H5T/test-pc.sh @@ -0,0 +1,264 @@ +#! /bin/sh +# +# Copyright by The HDF Group. +# Copyright by the Board of Trustees of the University of Illinois. +# 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 COPYING 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 is for use of h5cc created with the CMake process +# HDF5_HOME is expected to be set + +srcdir=.. +builddir=. +verbose=yes +nerrors=0 + +# HDF5 compile commands, assuming they are in your $PATH. +H5FC=$HDF5_HOME/bin/h5fc +LD_LIBRARY_PATH=$HDF5_HOME/lib +export LD_LIBRARY_PATH + +if ! test -f $H5FC; then + echo "Set paths for H5FC and LD_LIBRARY_PATH in test.sh" + echo "Set environment variable HDF5_HOME to the hdf5 install dir" + echo "h5fc was not found at $H5FC" + exit $EXIT_FAILURE +fi + +H5DUMP=`echo $H5FC | sed -e 's/\/[^/]*$/\/h5dump/'`; +H5_LIBVER=$($H5FC -showconfig | grep -i "HDF5 Version:" | sed 's/^.* //g' | sed 's/[-].*//g') +H5_APIVER=$($H5FC -showconfig | grep -i "Default API mapping:" | sed 's/^.* //g' | sed 's/v//g' | sed 's/1/1_/') + +H5_MAJORVER=$(echo $H5_LIBVER | cut -f1 -d'.' | sed -E 's/\./_/g') +H5_MINORVER=$(echo $H5_LIBVER | cut -f2 -d'.' | sed -E 's/\./_/g') +H5_RELEASEVER=$(echo $H5_LIBVER | cut -f3 -d'.' | sed -E 's/\./_/g') +H5_LIBVER_DIR=$H5_MAJORVER$H5_MINORVER + +# Shell commands used in Makefiles +RM="rm -rf" +DIFF="diff -c" +CMP="cmp -s" +GREP='grep' +CP="cp -p" # Use -p to preserve mode,ownership,timestamps +DIRNAME='dirname' +LS='ls' +AWK='awk' + +# setup plugin path +ENVCMD="env HDF5_PLUGIN_PATH=$LD_LIBRARY_PATH/plugin" + +TESTDIR=$builddir + + +case `echo "testing\c"; echo 1,2,3`,`echo -n testing; echo 1,2,3` in + *c*,-n*) ECHO_N= ECHO_C=' +' ;; + *c*,* ) ECHO_N=-n ECHO_C= ;; + *) ECHO_N= ECHO_C='\c' ;; +esac +ECHO_N="echo $ECHO_N" + + +exout() { + $* +} + +dumpout() { + $H5DUMP $* +} + +# compare current version, required version. +# returns if cur_ver < req_ver is true. +version_compare() { + version_lt=0 + if [ ! "$(printf '%s\n' "$1" "$2" | sort -V | head -n1)" = "$2" ]; then + version_lt=1 + fi +} + +FORTRAN_2003_CONDITIONAL_F="@FORTRAN_2003_CONDITIONAL_F@" + +topics="vlstring" + +if [ "$FORTRAN_2003_CONDITIONAL_F" = "Xyes" ]; then + topics="arrayatt_F03 array_F03 bitatt_F03 bit_F03 cmpdatt_F03 cmpd_F03 \ + Cstring_F03 enumatt_F03 enum_F03 floatatt_F03 float_F03 \ + intatt_F03 int_F03 opaqueatt_F03 opaque_F03 \ + string_F03 $topics" +fi + +return_val=0 + +for topic in $topics +do + $H5FC $srcdir/h5ex_t_$topic.F90 -o h5ex_t_$topic +done + +for topic in $topics +do + fname=h5ex_t_$topic + $ECHO_N "Testing FORTRAN/H5T/$fname...$ECHO_C" + exout ./$fname >tmp.test + cmp -s tmp.test $srcdir/tfiles/18/$fname.tst + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + if [[ $fname == "h5ex_t_cpxcmpd_F03" || $fname == "h5ex_t_cpxcmpdatt_F03" ]] + then + targ="-n" + else + targ="" + fi + dumpout $targ $fname.h5 >tmp.test + rm -f $fname.h5 + cmp -s tmp.test $srcdir/tfiles/18/$fname.ddl + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + echo " Passed" + fi + fi + return_val=`expr $status + $return_val` +done + + +#######Non-standard tests####### + +USE_ALT="" +if [ "$H5_LIBVER_DIR" = "110" ]; then + # check if HDF5 version is < 1.10.7 + version_compare "$H5_LIBVER" "1.10.7" + if [ "$version_lt" = 1 ]; then + USE_ALT="06" + fi +else + if [ "$H5_LIBVER_DIR" = "18" ]; then + # check if HDF5 version is < 1.8.22 + version_compare "$H5_LIBVER" "1.8.22" + if [ "$version_lt" = 1 ]; then + USE_ALT="21" + fi + fi +fi + +if [ "$FORTRAN_2003_CONDITIONAL_F" = "Xyes" ]; then + topics="objrefatt_F03 objref_F03 regrefatt_F03 regref_F03" +else + topics="" +fi + +for topic in $topics +do + $H5FC $srcdir/h5ex_t_$topic.F90 -o h5ex_t_$topic +done + +for topic in $topics +do + fname=h5ex_t_$topic + $ECHO_N "Testing FORTRAN/H5T/$fname...$ECHO_C" + exout ./$fname >tmp.test + cmp -s tmp.test $srcdir/tfiles/18/$fname.tst + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + dumpout $fname.h5 >tmp.test + rm -f $fname.h5 + version_compare "$H5_LIBVER" "1.10.0" + if [ "$version_lt" = 1 ]; then + cmp -s tmp.test $srcdir/tfiles/18/$fname$USE_ALT.ddl + else + version_compare "$H5_LIBVER" "1.12.0" + if [ "$version_lt" = 1 ]; then + version_compare "$H5_LIBVER" "1.10.7" + if [ "$version_lt" = 1 ]; then + cmp -s tmp.test $srcdir/tfiles/110/$fname$USE_ALT.ddl + else + cmp -s tmp.test $srcdir/tfiles/18/$fname.ddl + fi + else + cmp -s tmp.test $srcdir/tfiles/112/$fname.ddl + fi + fi + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + echo " Passed" + fi + fi + return_val=`expr $status + $return_val` +done + +topics="" +version_compare "$H5_LIBVER" "1.10.0" +if [ "$version_lt" = 0 ]; then + topics=" vlenatt_F03 vlen_F03" +fi + +for topic in $topics +do + $H5FC $srcdir/h5ex_t_$topic.F90 -o h5ex_t_$topic +done + +for topic in $topics +do + fname=h5ex_t_$topic + $ECHO_N "Testing C/H5T/$fname...$ECHO_C" + exout ./$fname >tmp.test + cmp -s tmp.test $srcdir/tfiles/18/$fname.tst + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + dumpout $fname.h5 >tmp.test + rm -f $fname.h5 + version_compare "$H5_LIBVER" "1.14.3" + if [ "$version_lt" = 1 ]; then + cmp -s tmp.test $srcdir/tfiles/18/$fname.ddl + else + cmp -s tmp.test $srcdir/tfiles/114/$fname.ddl + fi + status=$? + if test $status -ne 0 + then + echo " FAILED!" + else + echo " Passed" + fi + fi + return_val=`expr $status + $return_val` +done + +$H5FC $srcdir/h5ex_t_convert.F90 -o h5ex_t_convert + +#fname=h5ex_t_convert +#$ECHO_N "Testing FORTRAN/H5T/$fname...$ECHO_C" +#exout ./$fname >tmp.test +#cmp -s tmp.test $srcdir/tfiles/18/$fname.test +#status=$? +#if test $status -ne 0 +#then +# echo " FAILED!" +#else +# echo " Passed" +#fi +#return_val=`expr $status + $return_val` + + +rm -f tmp.test +echo "$return_val tests failed in /FORTRAN/H5T/" +exit $return_val diff --git a/config/cmake/LIBAEC/CMakeLists.txt b/config/cmake/LIBAEC/CMakeLists.txt index 29f1fc7f460..5d978275565 100644 --- a/config/cmake/LIBAEC/CMakeLists.txt +++ b/config/cmake/LIBAEC/CMakeLists.txt @@ -1,12 +1,12 @@ cmake_minimum_required (VERSION 3.18) -PROJECT (LIBAEC C) +project (LIBAEC C) #----------------------------------------------------------------------------- # Basic LIBAEC stuff here #----------------------------------------------------------------------------- -set(CMAKE_C_STANDARD 99) -set(CMAKE_C_VISIBILITY_PRESET hidden) -set(CMAKE_POSITION_INDEPENDENT_CODE ON) +set (CMAKE_C_STANDARD 99) +set (CMAKE_C_VISIBILITY_PRESET hidden) +set (CMAKE_POSITION_INDEPENDENT_CODE ON) set (LIBAEC_PACKAGE_EXT ${HDF_PACKAGE_EXT}) set (HDF_USE_GNU_DIRS ${HDF5_USE_GNU_DIRS}) @@ -22,30 +22,30 @@ if (WINDOWS) endif () if (NOT WINDOWS) -include(TestBigEndian) -test_big_endian(WORDS_BIGENDIAN) + include (TestBigEndian) + test_big_endian (WORDS_BIGENDIAN) endif () # Check for __builtin_clzll for faster decoding -include(CheckCSourceCompiles) +include (CheckCSourceCompiles) check_c_source_compiles( "int main(void)\n{return __builtin_clzll(1LL);}" HAVE_DECL___BUILTIN_CLZLL) -if(NOT HAVE_DECL___BUILTIN_CLZLL) +if (NOT HAVE_DECL___BUILTIN_CLZLL) # With MSVC we can use _BitScanReverse64 - check_c_source_compiles( + check_c_source_compiles ( "int main(void){unsigned long foo; unsigned __int64 bar=1LL; return _BitScanReverse64(&foo, bar);}" HAVE_BSR64) -endif() +endif () -include(CheckSymbolExists) -check_symbol_exists(snprintf "stdio.h" HAVE_SNPRINTF) -if(NOT HAVE_SNPRINTF) - check_symbol_exists(_snprintf "stdio.h" HAVE__SNPRINTF) - check_symbol_exists(_snprintf_s "stdio.h" HAVE__SNPRINTF_S) -endif() +include (CheckSymbolExists) +check_symbol_exists (snprintf "stdio.h" HAVE_SNPRINTF) +if (NOT HAVE_SNPRINTF) + check_symbol_exists (_snprintf "stdio.h" HAVE__SNPRINTF) + check_symbol_exists (_snprintf_s "stdio.h" HAVE__SNPRINTF_S) +endif () #----------------------------------------------------------------------------- # Define some CMake variables for use later in the project @@ -89,7 +89,6 @@ set (LIBAEC_PACKAGE_BUGREPORT "help@hdfgroup.org") set (LIBAEC_PACKAGE_SOVERSION "${libaec_VERS_MAJOR}.${libaec_VERS_MINOR}.${libaec_VERS_RELEASE}") set (LIBAEC_PACKAGE_SOVERSION_MAJOR "${libaec_VERS_MAJOR}") - HDF_DIR_PATHS(${LIBAEC_PACKAGE_NAME}) #----------------------------------------------------------------------------- @@ -100,28 +99,20 @@ if (NOT LIBAEC_EXPORTED_TARGETS) set (LIBAEC_EXPORTED_TARGETS "libaec-targets") endif () -#----------------------------------------------------------------------------- -# To include a library in the list exported by the project AT BUILD TIME, -# add it to this variable. This is NOT used by Make Install, but for projects -# which include SZIP as a sub-project within their build tree -#----------------------------------------------------------------------------- set_global_variable (LIBAEC_LIBRARIES_TO_EXPORT "") #----------------------------------------------------------------------------- -# Mac OS X Options +# All libs/tests/examples need the main include directories #----------------------------------------------------------------------------- -if (LIBAEC_BUILD_FRAMEWORKS AND NOT BUILD_SHARED_LIBS) - set (BUILD_SHARED_LIBS ON CACHE BOOL "Build Shared Libraries") -endif () +set_directory_properties (PROPERTIES INCLUDE_DIRECTORIES + "${LIBAEC_BINARY_DIR};${LIBAEC_SOURCE_DIR}/src;${CMAKE_RUNTIME_OUTPUT_DIRECTORY}" +) -set (CMAKE_POSITION_INDEPENDENT_CODE ON) +if (MSVC) + set (CMAKE_MFC_FLAG 0) + set(CMAKE_DEBUG_POSTFIX "d") +endif () -#----------------------------------------------------------------------------- -# When building utility executables that generate other (source) files : -# we make use of the following variables defined in the root CMakeLists. -# Certain systems may add /Debug or /Release to output paths -# and we need to call the executable from inside the CMake configuration -#----------------------------------------------------------------------------- set (EXE_EXT "") if (WIN32) set (EXE_EXT ".exe") @@ -130,10 +121,6 @@ if (WIN32) add_compile_definitions (_CONSOLE) endif () -if (MSVC) - set (CMAKE_MFC_FLAG 0) -endif () - #----------------------------------------------------------------------------- # Compiler specific flags : Shouldn't there be compiler tests for these #----------------------------------------------------------------------------- @@ -159,15 +146,13 @@ configure_file( "${CMAKE_CURRENT_BINARY_DIR}/libaec.h") #----------------------------------------------------------------------------- -# All libs/tests/examples need the main include directories +# Define LIBAEC Library #----------------------------------------------------------------------------- -set_directory_properties(PROPERTIES INCLUDE_DIRECTORIES - "${LIBAEC_BINARY_DIR};${LIBAEC_SOURCE_DIR}/src;${CMAKE_RUNTIME_OUTPUT_DIRECTORY}" + +set (LIBAEC_PUBLIC_HEADERS + ${CMAKE_CURRENT_BINARY_DIR}/libaec.h ) -#----------------------------------------------------------------------------- -# Define LIBAEC Library -#----------------------------------------------------------------------------- set(LIBAEC_SRCS ${LIBAEC_SRC_DIR}/encode.c ${LIBAEC_SRC_DIR}/encode_accessors.c @@ -175,10 +160,6 @@ set(LIBAEC_SRCS ${LIBAEC_SRC_DIR}/vector.c ) -set (LIBAEC_PUBLIC_HEADERS - ${CMAKE_CURRENT_BINARY_DIR}/libaec.h -) - add_library (${LIBAEC_LIB_TARGET} STATIC ${LIBAEC_SRCS} ${LIBAEC_PUBLIC_HEADERS}) target_include_directories (${LIBAEC_LIB_TARGET} PUBLIC "$" @@ -186,7 +167,6 @@ target_include_directories (${LIBAEC_LIB_TARGET} PUBLIC "$" "$") TARGET_C_PROPERTIES (${LIBAEC_LIB_TARGET} STATIC) -target_link_libraries (${LIBAEC_LIB_TARGET} PRIVATE ${LINK_LIBS}) H5_SET_LIB_OPTIONS (${LIBAEC_LIB_TARGET} ${LIBAEC_LIB_NAME} STATIC 0) set_target_properties (${LIBAEC_LIB_TARGET} PROPERTIES VERSION 0.0.12 SOVERSION 0 @@ -216,6 +196,7 @@ set_target_properties (${SZIP_LIB_TARGET} PROPERTIES LINKER_LANGUAGE C INTERFACE_INCLUDE_DIRECTORIES "$/include>" ) + set_global_variable (LIBAEC_LIBRARIES_TO_EXPORT "${LIBAEC_LIBRARIES_TO_EXPORT};${SZIP_LIB_TARGET}") set (install_targets ${install_targets} ${SZIP_LIB_TARGET}) @@ -240,31 +221,6 @@ endif () include (CMakePackageConfigHelpers) -#----------------------------------------------------------------------------- -# Add Target(s) to CMake Install for import into other projects -#----------------------------------------------------------------------------- -if (NOT LIBAEC_EXTERNALLY_CONFIGURED) - install ( - EXPORT ${LIBAEC_EXPORTED_TARGETS} - DESTINATION ${LIBAEC_INSTALL_CMAKE_DIR} - FILE ${LIBAEC_PACKAGE}${LIBAEC_PACKAGE_EXT}-targets.cmake - NAMESPACE ${PACKAGE_NAMESPACE} - COMPONENT configinstall - ) -endif () - -#----------------------------------------------------------------------------- -# Export all exported targets to the build tree for use by parent project -#----------------------------------------------------------------------------- -if (NOT LIBAEC_EXTERNALLY_CONFIGURED) - export ( - TARGETS ${LIBAEC_LIBRARIES_TO_EXPORT} ${LIBAEC_LIB_DEPENDENCIES} - FILE ${LIBAEC_PACKAGE}${LIBAEC_PACKAGE_EXT}-targets.cmake - NAMESPACE ${PACKAGE_NAMESPACE} - ) - export (PACKAGE ${LIBAEC_PACKAGE}${LIBAEC_PACKAGE_EXT}) -endif () - #----------------------------------------------------------------------------- # Set includes needed for build #----------------------------------------------------------------------------- @@ -328,3 +284,28 @@ if (NOT LIBAEC_EXTERNALLY_CONFIGURED) ) endif () +#----------------------------------------------------------------------------- +# Add Target(s) to CMake Install for import into other projects +#----------------------------------------------------------------------------- +if (NOT LIBAEC_EXTERNALLY_CONFIGURED) + install ( + EXPORT ${LIBAEC_EXPORTED_TARGETS} + DESTINATION ${LIBAEC_INSTALL_CMAKE_DIR} + FILE ${LIBAEC_PACKAGE}${LIBAEC_PACKAGE_EXT}-targets.cmake + NAMESPACE ${PACKAGE_NAMESPACE} + COMPONENT configinstall + ) +endif () + +#----------------------------------------------------------------------------- +# Export all exported targets to the build tree for use by parent project +#----------------------------------------------------------------------------- +if (NOT LIBAEC_EXTERNALLY_CONFIGURED) + export ( + TARGETS ${LIBAEC_LIBRARIES_TO_EXPORT} ${LIBAEC_LIB_DEPENDENCIES} + FILE ${LIBAEC_PACKAGE}${LIBAEC_PACKAGE_EXT}-targets.cmake + NAMESPACE ${PACKAGE_NAMESPACE} + ) + export (PACKAGE ${LIBAEC_PACKAGE}${LIBAEC_PACKAGE_EXT}) +endif () + diff --git a/config/cmake/ZLIB/CMakeLists.txt b/config/cmake/ZLIB/CMakeLists.txt index 78d678074b0..3dba6a89657 100644 --- a/config/cmake/ZLIB/CMakeLists.txt +++ b/config/cmake/ZLIB/CMakeLists.txt @@ -1,13 +1,14 @@ -cmake_minimum_required(VERSION 3.12.0) -set(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS ON) +cmake_minimum_required (VERSION 3.18) +set (CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS ON) +project (ZLIB C) -project(ZLIB C) - -set(VERSION "1.3") +set (VERSION "1.3") #----------------------------------------------------------------------------- # Basic ZLIB stuff here #----------------------------------------------------------------------------- +set (CMAKE_POSITION_INDEPENDENT_CODE ON) + set (ZLIB_PACKAGE_EXT ${HDF_PACKAGE_EXT}) set (HDF_USE_GNU_DIRS ${HDF5_USE_GNU_DIRS}) set (CMAKE_OSX_ARCHITECTURES ${CMAKE_OSX_ARCHITECTURES}) @@ -21,12 +22,95 @@ if (WINDOWS) set (HAVE_SYS_TYPES_H 1) endif () +include (CheckTypeSize) +include (CheckFunctionExists) +include (CheckIncludeFile) +include (CheckCSourceCompiles) + +check_include_file (sys/types.h HAVE_SYS_TYPES_H) +check_include_file (stdint.h HAVE_STDINT_H) +check_include_file (stddef.h HAVE_STDDEF_H) + +# +# Check to see if we have large file support +# +set (CMAKE_REQUIRED_DEFINITIONS -D_LARGEFILE64_SOURCE=1) +# We add these other definitions here because CheckTypeSize.cmake +# in CMake 2.4.x does not automatically do so and we want +# compatibility with CMake 2.4.x. +if (HAVE_SYS_TYPES_H) + list(APPEND CMAKE_REQUIRED_DEFINITIONS -DHAVE_SYS_TYPES_H) +endif () +if (HAVE_STDINT_H) + list(APPEND CMAKE_REQUIRED_DEFINITIONS -DHAVE_STDINT_H) +endif () +if (HAVE_STDDEF_H) + list(APPEND CMAKE_REQUIRED_DEFINITIONS -DHAVE_STDDEF_H) +endif () +check_type_size (off64_t OFF64_T) +if (HAVE_OFF64_T) + add_definitions(-D_LARGEFILE64_SOURCE=1) +endif () +set (CMAKE_REQUIRED_DEFINITIONS) # clear variable + +# +# Check for fseeko +# +check_function_exists (fseeko HAVE_FSEEKO) +if (NOT HAVE_FSEEKO) + add_definitions (-DNO_FSEEKO) +endif () + +# +# Check for unistd.h +# +check_include_file (unistd.h Z_HAVE_UNISTD_H) + #----------------------------------------------------------------------------- # Define some CMake variables for use later in the project #----------------------------------------------------------------------------- set (ZLIB_RESOURCES_DIR ${HDF_RESOURCES_DIR}/ZLIB) set (ZLIB_SRC_DIR ${ZLIB_SOURCE_DIR}) +#----------------------------------------------------------------------------- +# Set the core names of all the libraries +#----------------------------------------------------------------------------- +set (ZLIB_LIB_CORENAME "zlib-static") + +#----------------------------------------------------------------------------- +# Set the true names of all the libraries if customized by external project +#----------------------------------------------------------------------------- +set (ZLIB_LIB_NAME "${ZLIB_EXTERNAL_LIB_PREFIX}${ZLIB_LIB_CORENAME}") + +#----------------------------------------------------------------------------- +# Set the target names of all the libraries +#----------------------------------------------------------------------------- +set (ZLIB_LIB_TARGET "zlib-static") + +# parse the full version number from zlib.h and include in ZLIB_FULL_VERSION +file (READ ${CMAKE_CURRENT_SOURCE_DIR}/zlib.h _zlib_h_contents) +string (REGEX REPLACE ".*#define[ \t]+ZLIB_VERSION[ \t]+\"([-0-9A-Za-z.]+)\".*" + "\\1" ZLIB_FULL_VERSION ${_zlib_h_contents}) + +set (zlib_VERS_MAJOR 1) +set (zlib_VERS_MINOR 3) +set (zlib_VERS_RELEASE 0) + +#----------------------------------------------------------------------------- +set (ZLIB_PACKAGE "zlib") +set (ZLIB_PACKAGE_NAME "ZLIB") +set (ZLIB_PACKAGE_VERSION "${zlib_VERS_MAJOR}.${zlib_VERS_MINOR}") +set (ZLIB_PACKAGE_VERSION_MAJOR "${zlib_VERS_MAJOR}.${zlib_VERS_MINOR}") +set (ZLIB_PACKAGE_VERSION_MINOR "${zlib_VERS_RELEASE}") +set (ZLIB_PACKAGE_STRING "${ZLIB_PACKAGE_NAME} ${ZLIB_PACKAGE_VERSION}") +set (ZLIB_PACKAGE_TARNAME "${ZLIB_PACKAGE_NAME}${ZLIB_PACKAGE_EXT}") +set (ZLIB_PACKAGE_URL "http://www.hdfgroup.org") +set (ZLIB_PACKAGE_BUGREPORT "help@hdfgroup.org") +set (ZLIB_PACKAGE_SOVERSION "${zlib_VERS_MAJOR}.${zlib_VERS_MINOR}.${zlib_VERS_RELEASE}") +set (ZLIB_PACKAGE_SOVERSION_MAJOR "${zlib_VERS_MAJOR}") + +HDF_DIR_PATHS(${ZLIB_PACKAGE_NAME}) + #----------------------------------------------------------------------------- # Targets built within this project are exported at Install time for use # by other projects @@ -35,69 +119,23 @@ if (NOT ZLIB_EXPORTED_TARGETS) set (ZLIB_EXPORTED_TARGETS "zlib-targets") endif () -set (CMAKE_POSITION_INDEPENDENT_CODE ON) - -HDF_DIR_PATHS(ZLIB) +set_global_variable (ZLIB_LIBRARIES_TO_EXPORT "") #----------------------------------------------------------------------------- # All libs/tests/examples need the main include directories #----------------------------------------------------------------------------- -set_directory_properties(PROPERTIES INCLUDE_DIRECTORIES +set_directory_properties (PROPERTIES INCLUDE_DIRECTORIES "${ZLIB_BINARY_DIR};${ZLIB_SOURCE_DIR};${CMAKE_RUNTIME_OUTPUT_DIRECTORY}" ) -include(CheckTypeSize) -include(CheckFunctionExists) -include(CheckIncludeFile) -include(CheckCSourceCompiles) - -check_include_file(sys/types.h HAVE_SYS_TYPES_H) -check_include_file(stdint.h HAVE_STDINT_H) -check_include_file(stddef.h HAVE_STDDEF_H) - -# -# Check to see if we have large file support -# -set(CMAKE_REQUIRED_DEFINITIONS -D_LARGEFILE64_SOURCE=1) -# We add these other definitions here because CheckTypeSize.cmake -# in CMake 2.4.x does not automatically do so and we want -# compatibility with CMake 2.4.x. -if(HAVE_SYS_TYPES_H) - list(APPEND CMAKE_REQUIRED_DEFINITIONS -DHAVE_SYS_TYPES_H) -endif() -if(HAVE_STDINT_H) - list(APPEND CMAKE_REQUIRED_DEFINITIONS -DHAVE_STDINT_H) -endif() -if(HAVE_STDDEF_H) - list(APPEND CMAKE_REQUIRED_DEFINITIONS -DHAVE_STDDEF_H) -endif() -check_type_size(off64_t OFF64_T) -if(HAVE_OFF64_T) - add_definitions(-D_LARGEFILE64_SOURCE=1) -endif() -set(CMAKE_REQUIRED_DEFINITIONS) # clear variable - -# -# Check for fseeko -# -check_function_exists(fseeko HAVE_FSEEKO) -if(NOT HAVE_FSEEKO) - add_definitions(-DNO_FSEEKO) -endif() - -# -# Check for unistd.h -# -check_include_file(unistd.h Z_HAVE_UNISTD_H) - -if(MSVC) - set(CMAKE_DEBUG_POSTFIX "d") - add_definitions (-D_BIND_TO_CURRENT_VCLIBS_VERSION=1) - add_definitions (-D_CRT_SECURE_NO_WARNINGS) - add_definitions (-D_CONSOLE) - add_definitions(-D_CRT_NONSTDC_NO_DEPRECATE) - include_directories(${CMAKE_CURRENT_SOURCE_DIR}) -endif() +if (MSVC) + set(CMAKE_DEBUG_POSTFIX "d") + add_definitions (-D_BIND_TO_CURRENT_VCLIBS_VERSION=1) + add_definitions (-D_CRT_SECURE_NO_WARNINGS) + add_definitions (-D_CONSOLE) + add_definitions(-D_CRT_NONSTDC_NO_DEPRECATE) + include_directories(${CMAKE_CURRENT_SOURCE_DIR}) +endif () if(NOT CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_CURRENT_BINARY_DIR) # If we're doing an out of source build and the user has a zconf.h @@ -115,9 +153,9 @@ configure_file( ${CMAKE_CURRENT_SOURCE_DIR}/zconf.h.cmakein include_directories(${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_SOURCE_DIR}) -#============================================================================ -# zlib -#============================================================================ +#----------------------------------------------------------------------------- +# Define ZLIB Library +#----------------------------------------------------------------------------- set(ZLIB_PUBLIC_HDRS ${CMAKE_CURRENT_BINARY_DIR}/zconf.h @@ -152,47 +190,40 @@ set(ZLIB_SRCS zutil.c ) -# parse the full version number from zlib.h and include in ZLIB_FULL_VERSION -file(READ ${CMAKE_CURRENT_SOURCE_DIR}/zlib.h _zlib_h_contents) -string(REGEX REPLACE ".*#define[ \t]+ZLIB_VERSION[ \t]+\"([-0-9A-Za-z.]+)\".*" - "\\1" ZLIB_FULL_VERSION ${_zlib_h_contents}) - -add_library(zlib-static STATIC ${ZLIB_SRCS} ${ZLIB_PUBLIC_HDRS} ${ZLIB_PRIVATE_HDRS}) +add_library(${ZLIB_LIB_TARGET} STATIC ${ZLIB_SRCS} ${ZLIB_PUBLIC_HDRS} ${ZLIB_PRIVATE_HDRS}) +target_include_directories(${ZLIB_LIB_TARGET} PRIVATE "${CMAKE_BINARY_DIR}") if (MSVC AND CMAKE_CL_64) - set_target_properties (zlib-static PROPERTIES STATIC_LIBRARY_FLAGS "/machine:x64") + set_target_properties (${ZLIB_LIB_TARGET} PROPERTIES STATIC_LIBRARY_FLAGS "/machine:x64") endif () -target_include_directories(zlib-static PRIVATE "${CMAKE_BINARY_DIR}") -set_target_properties(zlib-static PROPERTIES +set_target_properties(${ZLIB_LIB_TARGET} PROPERTIES PUBLIC_HEADER "" LINKER_LANGUAGE C INTERFACE_INCLUDE_DIRECTORIES "$/include>" ) -set_global_variable (ZLIB_LIBRARIES_TO_EXPORT "zlib-static") -set (install_targets zlib-static) #----------------------------------------------------------------------------- -# Compiler specific flags : Shouldn't there be compiler tests for these +# Compiler specific flags #----------------------------------------------------------------------------- if (CMAKE_C_COMPILER_ID STREQUAL "GNU") - target_compile_options(zlib-static PRIVATE -Wno-strict-prototypes -Wno-implicit-function-declaration) + target_compile_options(${ZLIB_LIB_TARGET} PRIVATE -Wno-strict-prototypes -Wno-implicit-function-declaration) endif () if (CMAKE_C_COMPILER_ID MATCHES "IntelLLVM" OR CMAKE_C_COMPILER_ID MATCHES "[Cc]lang") - target_compile_options(zlib-static PRIVATE -Wno-implicit-function-declaration) + target_compile_options(${ZLIB_LIB_TARGET} PRIVATE -Wno-implicit-function-declaration) endif () - -#----------------------------------------------------------------------------- -# This is in here to help some of the GCC based IDES like Eclipse -# and code blocks parse the compiler errors and warnings better. -#----------------------------------------------------------------------------- if (CMAKE_C_COMPILER_ID STREQUAL "GNU") - target_compile_options(zlib-static PRIVATE -fmessage-length=0) + target_compile_options(${ZLIB_LIB_TARGET} PRIVATE -fmessage-length=0) endif () +set_target_properties(${ZLIB_LIB_TARGET} PROPERTIES OUTPUT_NAME zlib-static) + +set_global_variable (ZLIB_LIBRARIES_TO_EXPORT "${ZLIB_LIB_TARGET}") +set (install_targets ${ZLIB_LIB_TARGET}) + #----------------------------------------------------------------------------- # Add Target(s) to CMake Install for import into other projects #----------------------------------------------------------------------------- if (ZLIB_EXPORTED_TARGETS) - INSTALL_TARGET_PDB (zlib-static ${ZLIB_INSTALL_BIN_DIR} libraries) + INSTALL_TARGET_PDB (${ZLIB_LIB_TARGET} ${ZLIB_INSTALL_BIN_DIR} libraries) install ( TARGETS @@ -228,7 +259,7 @@ configure_package_config_file ( #----------------------------------------------------------------------------- set (INCLUDE_INSTALL_DIR ${ZLIB_INSTALL_INCLUDE_DIR}) set (SHARE_INSTALL_DIR "${CMAKE_INSTALL_PREFIX}/${ZLIB_INSTALL_CMAKE_DIR}" ) -set (CURRENT_BUILD_DIR "${CMAKE_INSTALL_PREFIX}" ) +set (CURRENT_BUILD_DIR "${CMAKE_INSTALL_PREFIX}") configure_package_config_file ( ${ZLIB_RESOURCES_DIR}/zlib-config.cmake.in "${ZLIB_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/zlib-config.cmake" diff --git a/config/cmake/ZLIBNG/CMakeLists.txt b/config/cmake/ZLIBNG/CMakeLists.txt index 64e39d7500c..5bb5da961e1 100644 --- a/config/cmake/ZLIBNG/CMakeLists.txt +++ b/config/cmake/ZLIBNG/CMakeLists.txt @@ -1,4 +1,6 @@ -cmake_minimum_required(VERSION 3.12) +cmake_minimum_required(VERSION 3.18) +project(ZLIB VERSION ${ZLIB_HEADER_VERSION} LANGUAGES C) + message(STATUS "Using CMake version ${CMAKE_VERSION}") # If not specified on the command line, enable C11 as the default @@ -27,8 +29,6 @@ string(REGEX REPLACE ".*#define[ \t]+ZLIBNG_VERSION[ \t]+\"([-0-9A-Za-z.]+)\".*" message(STATUS "ZLIB_HEADER_VERSION: ${ZLIB_HEADER_VERSION}") message(STATUS "ZLIBNG_HEADER_VERSION: ${ZLIBNG_HEADER_VERSION}") -project(ZLIB VERSION ${ZLIB_HEADER_VERSION} LANGUAGES C) - #----------------------------------------------------------------------------- # Basic ZLIB stuff here #----------------------------------------------------------------------------- @@ -983,9 +983,9 @@ if(NOT CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_CURRENT_BINARY_DIR) endif() -#============================================================================ -# zlib -#============================================================================ +#----------------------------------------------------------------------------- +# Define ZLIB Library +#----------------------------------------------------------------------------- set(ZLIB_PUBLIC_HDRS ${CMAKE_CURRENT_BINARY_DIR}/zconf${SUFFIX}.h @@ -1075,7 +1075,7 @@ set_global_variable (ZLIB_LIBRARIES_TO_EXPORT "zlib-static") set (install_targets zlib-static) #----------------------------------------------------------------------------- -# Compiler specific flags : Shouldn't there be compiler tests for these +# Compiler specific flags #----------------------------------------------------------------------------- if (CMAKE_C_COMPILER_ID STREQUAL "GNU") target_compile_options(zlib-static PRIVATE -Wno-strict-prototypes -Wno-implicit-function-declaration) @@ -1167,7 +1167,7 @@ configure_package_config_file ( #----------------------------------------------------------------------------- set (INCLUDE_INSTALL_DIR ${ZLIB_INSTALL_INCLUDE_DIR}) set (SHARE_INSTALL_DIR "${CMAKE_INSTALL_PREFIX}/${ZLIB_INSTALL_CMAKE_DIR}" ) -set (CURRENT_BUILD_DIR "${CMAKE_INSTALL_PREFIX}" ) +set (CURRENT_BUILD_DIR "${CMAKE_INSTALL_PREFIX}") configure_package_config_file ( ${ZLIB_RESOURCES_DIR}/zlib-config.cmake.in "${ZLIB_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/zlib-config.cmake" diff --git a/config/cmake/libh5cc.in b/config/cmake/libh5cc.in index 4d2584809c4..9bdce64f7df 100644 --- a/config/cmake/libh5cc.in +++ b/config/cmake/libh5cc.in @@ -21,11 +21,12 @@ fi dir=$( cd -P -- "$(dirname -- "$prg")/.." && pwd -P ) || exit -prg=$dir/$(basename -- "$prg") || exit +prg=$dir/bin/$(basename -- "$prg") || exit -printf '%s\n' "$prg" -printf 'dir is %s\n' "$dir" +#printf '%s\n' "$prg" +#printf 'dir is %s\n' "$dir" +pc_args="" # Show the configuration summary of the library recorded in the # libhdf5.settings file residing in the lib directory. @@ -35,6 +36,27 @@ showconfigure() status=$? } +usage() { + # "How-to use" message. + echo "usage: $prg [OPTIONS] " + echo " OPTIONS:" + echo " -help This help message." + echo " -show Show the commands without executing them" + echo " -showconfig Show the HDF5 library configuration summary" + echo " " + echo " - the pkg-config compile line options for the compiler" + echo " that was used to compile HDF5." + echo " Use pkg-config --help for more information" + echo " on which options are available. $prg passes pkg-config options" + echo " through as those options use double-underscores." + echo " " + echo " NOTE: pkg-config is required to be installed on your system and" + echo " using --static requires a static version of the C runtime library" + echo " to be have been installed on your system." + echo " " + exit $EXIT_FAILURE +} + export PKG_CONFIG_PATH=$dir/lib/pkgconfig for arg in $@ ; do @@ -43,8 +65,20 @@ for arg in $@ ; do showconfigure exit $status ;; + -show) + echo @_PKG_CONFIG_COMPILER@ $@ `pkg-config $pc_args --define-variable=prefix=$dir --cflags --libs @_PKG_CONFIG_LIBNAME@` + exit $status + ;; + -help) + usage + exit $status + ;; + --*) + # gather pkg-config specific options + pc_args="$pc_args $arg" + ;; *) - @_PKG_CONFIG_COMPILER@ $@ `pkg-config --define-variable=prefix=$dir --cflags --libs @_PKG_CONFIG_LIBNAME@` + @_PKG_CONFIG_COMPILER@ $@ `pkg-config $pc_args --define-variable=prefix=$dir --cflags --libs @_PKG_CONFIG_LIBNAME@` status=$? exit $status ;; diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index c6743a85ff7..2d474b877f0 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -1194,20 +1194,21 @@ if (${HDF_CFG_NAME} MATCHES "Debug" OR ${HDF_CFG_NAME} MATCHES "Developer") set (PKGCONFIG_LIBNAME "${PKGCONFIG_LIBNAME}${CMAKE_DEBUG_POSTFIX}") endif () -foreach (libs ${LINK_LIBS}) - set (_PKG_CONFIG_LIBS_PRIVATE "${_PKG_CONFIG_LIBS_PRIVATE} -l${libs}") -endforeach () +#foreach (libs ${LINK_LIBS}) +# set (_PKG_CONFIG_LIBS_PRIVATE "${_PKG_CONFIG_LIBS_PRIVATE} -l${libs}") +#endforeach () # The settings for the compression libs depends on if they have pkconfig support # Assuming they don't foreach (libs ${LINK_COMP_LIBS}) # set (_PKG_CONFIG_REQUIRES_PRIVATE "${_PKG_CONFIG_REQUIRES_PRIVATE} -l${libs}") - set (_PKG_CONFIG_LIBS_PRIVATE "${_PKG_CONFIG_LIBS_PRIVATE} -l${libs}") + get_target_property (libname ${libs} OUTPUT_NAME) + set (_PKG_CONFIG_LIBS_PRIVATE "${_PKG_CONFIG_LIBS_PRIVATE} -l${libname}") endforeach () -if (BUILD_STATIC_LIBS) - set (_PKG_CONFIG_LIBS "${_PKG_CONFIG_LIBS} -l${PKGCONFIG_LIBNAME}") -endif () +#if (BUILD_STATIC_LIBS) +# set (_PKG_CONFIG_LIBS "${_PKG_CONFIG_LIBS} -l${PKGCONFIG_LIBNAME}") +#endif () if (BUILD_SHARED_LIBS) set (_PKG_CONFIG_SH_LIBS "${_PKG_CONFIG_SH_LIBS} -l${PKGCONFIG_LIBNAME}") endif () From 74fbc1dbd45be8551df666205282426e3948ce93 Mon Sep 17 00:00:00 2001 From: jhendersonHDF Date: Mon, 15 Jul 2024 11:28:13 -0500 Subject: [PATCH 05/20] Add temporary fix for ARM64 Mac _Float16 build failure (#4639) --- .github/workflows/main-cmake.yml | 2 +- src/H5private.h | 8 +++++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/main-cmake.yml b/.github/workflows/main-cmake.yml index e1de81ba16e..897f15c9844 100644 --- a/.github/workflows/main-cmake.yml +++ b/.github/workflows/main-cmake.yml @@ -110,7 +110,7 @@ jobs: # but that seems unnecessary - name: "MacOS Clang" os: macos-latest - cpp: OFF + cpp: ON fortran: ON java: ON docs: ON diff --git a/src/H5private.h b/src/H5private.h index c7a622ebd22..43412735b41 100644 --- a/src/H5private.h +++ b/src/H5private.h @@ -586,8 +586,14 @@ * _Float16 type to avoid issues when compiling the library * with the -pedantic flag or similar where we get warnings * about _Float16 not being an ISO C type. + * + * Due to the inclusion of H5private.h from the C++ wrappers, + * this typedef creation must be avoided when __cplusplus is + * defined to avoid build failures on ARM64 Macs. GCC and + * Clang either do not currently provide a _Float16 type for + * C++ on ARM64, or may need an additional compile-time flag. */ -#ifdef H5_HAVE__FLOAT16 +#if defined(H5_HAVE__FLOAT16) && !defined(__cplusplus) #if defined(__GNUC__) __extension__ typedef _Float16 H5__Float16; #else From e6e098b7c341159fcbcea23a3c283b7906cf6301 Mon Sep 17 00:00:00 2001 From: mattjala <124107509+mattjala@users.noreply.github.com> Date: Mon, 15 Jul 2024 13:01:15 -0500 Subject: [PATCH 06/20] Correct H5VL_t ref count on H5O_refresh_metadata failure (#4636) * Fix bad H5VL_t rc on H5O_refresh_metadata fail * Decrement nrefs before raising error --- src/H5Oflush.c | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/H5Oflush.c b/src/H5Oflush.c index 1c561d00b8b..dd11c25e7ca 100644 --- a/src/H5Oflush.c +++ b/src/H5Oflush.c @@ -235,12 +235,16 @@ H5O_refresh_metadata(H5O_loc_t *oloc, hid_t oid) connector->nrefs++; /* Close object & evict its metadata */ - if (H5O__refresh_metadata_close(oloc, &obj_loc, oid) < 0) + if (H5O__refresh_metadata_close(oloc, &obj_loc, oid) < 0) { + connector->nrefs--; HGOTO_ERROR(H5E_OHDR, H5E_CANTLOAD, FAIL, "unable to refresh object"); + } /* Re-open the object, re-fetching its metadata */ - if (H5O_refresh_metadata_reopen(oid, H5P_DEFAULT, &obj_loc, connector, false) < 0) + if (H5O_refresh_metadata_reopen(oid, H5P_DEFAULT, &obj_loc, connector, false) < 0) { + connector->nrefs--; HGOTO_ERROR(H5E_OHDR, H5E_CANTLOAD, FAIL, "unable to refresh object"); + } /* Restore the number of references on the VOL connector */ connector->nrefs--; From e71605966aa4ea9fbd8a29c1c184e431bfa19226 Mon Sep 17 00:00:00 2001 From: Allen Byrne <50328838+byrnHDF@users.noreply.github.com> Date: Mon, 15 Jul 2024 22:02:08 -0500 Subject: [PATCH 07/20] Update doxygen Learn Basics / example refs. Add Reference sections (#4640) --- ...a => HDF5GroupAbsoluteRelativeCreate.java} | 6 +- HDF5Examples/JAVA/TUTR/Java_sourcefiles.cmake | 1 + .../110/HDF5GroupAbsoluteRelativeCreate.txt | 0 doxygen/aliases | 10 +- doxygen/dox/IntroHDF5.dox | 24 +- doxygen/dox/LearnBasics.dox | 18 +- doxygen/dox/LearnBasics1.dox | 116 +++--- doxygen/dox/LearnBasics2.dox | 40 +- doxygen/dox/ViewTools.dox | 160 +++++++- fortran/src/H5Fff.F90 | 2 +- hl/src/H5DOpublic.h | 2 +- hl/src/H5DSpublic.h | 2 +- hl/src/H5IMpublic.h | 2 +- hl/src/H5LTpublic.h | 2 +- hl/src/H5PTpublic.h | 2 +- hl/src/H5TBpublic.h | 2 +- src/H5Dmodule.h | 14 +- src/H5ESmodule.h | 2 +- src/H5Fmodule.h | 2 +- src/H5Imodule.h | 2 +- src/H5Lmodule.h | 2 +- src/H5Mmodule.h | 4 +- src/H5Omodule.h | 2 +- src/H5PLmodule.h | 2 +- src/H5Rmodule.h | 368 +++++++++++++++++- src/H5Smodule.h | 40 +- src/H5Tmodule.h | 68 +++- src/H5VLmodule.h | 2 +- src/H5Zmodule.h | 2 +- src/H5module.h | 4 +- 30 files changed, 788 insertions(+), 115 deletions(-) rename HDF5Examples/JAVA/TUTR/{H5_CreateGroupAbsoluteRelative.java => HDF5GroupAbsoluteRelativeCreate.java} (95%) create mode 100644 HDF5Examples/JAVA/TUTR/tfiles/110/HDF5GroupAbsoluteRelativeCreate.txt diff --git a/HDF5Examples/JAVA/TUTR/H5_CreateGroupAbsoluteRelative.java b/HDF5Examples/JAVA/TUTR/HDF5GroupAbsoluteRelativeCreate.java similarity index 95% rename from HDF5Examples/JAVA/TUTR/H5_CreateGroupAbsoluteRelative.java rename to HDF5Examples/JAVA/TUTR/HDF5GroupAbsoluteRelativeCreate.java index 934242de798..9061c31c44f 100644 --- a/HDF5Examples/JAVA/TUTR/H5_CreateGroupAbsoluteRelative.java +++ b/HDF5Examples/JAVA/TUTR/HDF5GroupAbsoluteRelativeCreate.java @@ -17,8 +17,8 @@ import hdf.hdf5lib.H5; import hdf.hdf5lib.HDF5Constants; -public class H5_CreateGroupAbsoluteRelative { - private static String FILENAME = "H5_CreateGroupAbsoluteRelative.h5"; +public class HDF5GroupAbsoluteRelativeCreate { + private static String FILENAME = "HDF5GroupAbsoluteRelativeCreate.h5"; private static String GROUPNAME = "MyGroup"; private static String GROUPNAME_A = "GroupA"; private static String GROUPNAME_B = "GroupB"; @@ -109,6 +109,6 @@ private static void CreateGroupAbsoluteAndRelative() public static void main(String[] args) { - H5_CreateGroupAbsoluteRelative.CreateGroupAbsoluteAndRelative(); + HDF5GroupAbsoluteRelativeCreate.CreateGroupAbsoluteAndRelative(); } } diff --git a/HDF5Examples/JAVA/TUTR/Java_sourcefiles.cmake b/HDF5Examples/JAVA/TUTR/Java_sourcefiles.cmake index e78e12e0e87..a291cf354ad 100644 --- a/HDF5Examples/JAVA/TUTR/Java_sourcefiles.cmake +++ b/HDF5Examples/JAVA/TUTR/Java_sourcefiles.cmake @@ -9,6 +9,7 @@ set (HDF_JAVA_EXAMPLES HDF5DatasetRead.java HDF5GroupDatasetCreate.java HDF5SubsetSelect.java + HDF5GroupAbsoluteRelativeCreate.java ) if (H5_LIBVER_DIR EQUAL 110) set (HDF_JAVA_EXAMPLES ${HDF_JAVA_EXAMPLES} diff --git a/HDF5Examples/JAVA/TUTR/tfiles/110/HDF5GroupAbsoluteRelativeCreate.txt b/HDF5Examples/JAVA/TUTR/tfiles/110/HDF5GroupAbsoluteRelativeCreate.txt new file mode 100644 index 00000000000..e69de29bb2d diff --git a/doxygen/aliases b/doxygen/aliases index 19656fac29b..da412d5c8f1 100644 --- a/doxygen/aliases +++ b/doxygen/aliases @@ -3,18 +3,26 @@ ALIASES += THG="The HDF Group" ################################################################################ # Default URLs (Note that md files do not use any aliases) ################################################################################ +# Default URL for HDF Group Files ALIASES += HDFURL="docs.hdfgroup.org/hdf5" +# URL for archived files ALIASES += ARCURL="docs.hdfgroup.org/archive/support/HDF5/doc" +# URL for RFCs ALIASES += RFCURL="docs.hdfgroup.org/hdf5/rfc" +# URL for documentation ALIASES += DSPURL="portal.hdfgroup.org/display/HDF5" ALIASES += DOCURL="portal.hdfgroup.org/documentation/hdf5-docs" +# URL for downloads ALIASES += DWNURL="portal.hdfgroup.org/downloads" ALIASES += AEXURL="support.hdfgroup.org/ftp/HDF5/examples" # doxygen subdir (develop, v1_14) ALIASES += DOXURL="hdfgroup.github.io/hdf5/develop" #branch name (develop, hdf5_1_14) ALIASES += SRCURL="github.com/HDFGroup/hdf5/blob/develop" - +#Other projects that contribute to HDF5 +ALIASES += PRJURL="\HDFURL/projects" +ALIASES += HVURL="github.com/HDFGroup/hdfview/blob/master" +ALIASES += PLURL="github.com/HDFGroup/hdf5_plugins/blob/master" ################################################################################ # Styling ################################################################################ diff --git a/doxygen/dox/IntroHDF5.dox b/doxygen/dox/IntroHDF5.dox index 737b17de4ba..9ef55d3a573 100644 --- a/doxygen/dox/IntroHDF5.dox +++ b/doxygen/dox/IntroHDF5.dox @@ -298,19 +298,27 @@ hsize_t is used for dimensions Language specific files must be included in applications:
  • -Python: Add "import h5py / import numpy" +Python:
    + +import h5py
    +import numpy +
  • -C: Add "#include hdf5.h" +C:
    +"#include hdf5.h"
  • -FORTRAN: Add "USE HDF5" and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface +FORTRAN:
    +USE HDF5
    +and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface
  • -Java: Add "import hdf.hdf5lib.H5; - import hdf.hdf5lib.HDF5Constants;" -
    • -
+Java:
+ +import hdf.hdf5lib.H5;
+import hdf.hdf5lib.HDF5Constants; + @@ -608,7 +616,7 @@ on the HDF-EOS Tools and Information Center pag \section secHDF5Examples Examples \li \ref LBExamples \li \ref ExAPI -\li Examples in the Source Code +\li Examples in the Source Code \li Other Examples \section secHDF5ExamplesCompile How To Compile diff --git a/doxygen/dox/LearnBasics.dox b/doxygen/dox/LearnBasics.dox index 68700b8df83..ed83b367b6b 100644 --- a/doxygen/dox/LearnBasics.dox +++ b/doxygen/dox/LearnBasics.dox @@ -41,7 +41,7 @@ Navigate back: \ref index "Main" / \ref GettingStarted Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics
-\section secLBExamples +\section secLBExamples HDF5 Examples These examples are used in the \ref LearnBasics topic. See \ref LBCompiling for details on compiling them. PLEASE NOTE that the example programs are listed in the order they are expected to be run. Some example programs use files created in earlier examples. @@ -59,7 +59,7 @@ These examples (C, C++, Fortran, Java, Python) are provided in the HDF5 source c Create a file -C Fortran C++ Java Python +C Fortran C++ Java Python @@ -67,7 +67,7 @@ These examples (C, C++, Fortran, Java, Python) are provided in the HDF5 source c Create a dataset -C Fortran C++ Java Python +C Fortran C++ Java Python @@ -75,7 +75,7 @@ These examples (C, C++, Fortran, Java, Python) are provided in the HDF5 source c Read and write to a dataset -C Fortran C++ Java Python +C Fortran C++ Java Python @@ -83,7 +83,7 @@ These examples (C, C++, Fortran, Java, Python) are provided in the HDF5 source c Create an attribute -C Fortran C++ Java Python +C Fortran C++ Java Python @@ -91,7 +91,7 @@ These examples (C, C++, Fortran, Java, Python) are provided in the HDF5 source c Create a group -C Fortran C++ Java Python +C Fortran C++ Java Python @@ -99,7 +99,7 @@ These examples (C, C++, Fortran, Java, Python) are provided in the HDF5 source c Create groups in a file using absolute and relative paths -C Fortran C++ Java Python +C Fortran C++ Java Python @@ -107,7 +107,7 @@ These examples (C, C++, Fortran, Java, Python) are provided in the HDF5 source c Create datasets in a group -C Fortran C++ Java Python +C Fortran C++ Java Python @@ -115,7 +115,7 @@ These examples (C, C++, Fortran, Java, Python) are provided in the HDF5 source c Create a file and dataset and select/read a subset from the dataset -C Fortran C++ Java Python +C Fortran C++ Java Python Also see examples to Write by row (and column) below. diff --git a/doxygen/dox/LearnBasics1.dox b/doxygen/dox/LearnBasics1.dox index 64ba30ea9bf..f4b44d1cf89 100644 --- a/doxygen/dox/LearnBasics1.dox +++ b/doxygen/dox/LearnBasics1.dox @@ -53,86 +53,86 @@ The APIs are listed below: -H5 - +@ref H5_UG + Library Functions: general-purpose H5 functions -H5A - +@ref H5A_UG + Annotation Interface: attribute access and manipulation routines -H5D - +@ref H5D_UG + Dataset Interface: dataset access and manipulation routines -H5E - +@ref H5E_UG + Error Interface: error handling routines -H5F - +@ref H5F_UG + File Interface: file access routines -H5G - +@ref H5G_UG + Group Interface: group creation and operation routines -H5I - +@ref H5I_UG + Identifier Interface: identifier routines -H5L - +@ref H5L_UG + Link Interface: link routines -H5O - +@ref H5O_UG + Object Interface: object routines -H5P - +@ref H5P_UG + Property List Interface: object property list manipulation routines -H5R - +@ref H5R_UG + Reference Interface: reference routines -H5S - +@ref H5S_UG + Dataspace Interface: dataspace definition and access routines -H5T - +@ref H5T_UG + Datatype Interface: datatype creation and manipulation routines -H5Z - +@ref H5Z_UG + Compression Interface: compression routine(s) @@ -189,26 +189,38 @@ in the HDF5Constants class and are prefixed with "HDF5Constants.".: \section LBProgTypes HDF5 library has its own defined types \li #hid_t is used for object handles -\li hsize_t is used for dimensions +\li #hsize_t is used for dimensions \li #herr_t is used for many return values \section LBProgLang Language specific files must be included in applications
  • -Python: Add "import h5py / import numpy" +Python:
    + +import h5py
    +import numpy +
  • -C: Add "#include hdf5.h" +C:
    +"#include hdf5.h"
  • -FORTRAN: Add "USE HDF5" and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface +FORTRAN:
    +USE HDF5
    +and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface
  • -Java: Add "import hdf.hdf5lib.H5; - import hdf.hdf5lib.HDF5Constants;" +Java:
    + +import hdf.hdf5lib.H5;
    +import hdf.hdf5lib.HDF5Constants; +
+@see @ref ExAPI for examples of using the HDF5 API. +
Previous Chapter \ref LBAPI - Next Chapter \ref LBFileCreate @@ -461,23 +473,23 @@ Some of the HDF5 predefined atomic datatypes are listed below. Description -H5T_STD_I32LE +#H5T_STD_I32LE Four-byte, little-endian, signed, two's complement integer -H5T_STD_U16BE +#H5T_STD_U16BE Two-byte, big-endian, unsigned integer -H5T_IEEE_F32BE +#H5T_IEEE_F32BE Four-byte, big-endian, IEEE floating point -H5T_IEEE_F64LE +#H5T_IEEE_F64LE Eight-byte, little-endian, IEEE floating point -H5T_C_S1 +#H5T_C_S1 One-byte, null-terminated string of eight-bit characters @@ -492,42 +504,42 @@ Some of the HDF5 predefined atomic datatypes are listed below. C -H5T_NATIVE_INT +#H5T_NATIVE_INT int -H5T_NATIVE_FLOAT +#H5T_NATIVE_FLOAT float -H5T_NATIVE_CHAR +#H5T_NATIVE_CHAR char -H5T_NATIVE_DOUBLE +#H5T_NATIVE_DOUBLE double -H5T_NATIVE_LDOUBLE +#H5T_NATIVE_LDOUBLE long double Fortran -H5T_NATIVE_INTEGER +H5T_NATIVE_INTEGER integer -H5T_NATIVE_REAL +H5T_NATIVE_REAL real -H5T_NATIVE_DOUBLE +H5T_NATIVE_DOUBLE double precision -H5T_NATIVE_CHARACTER +H5T_NATIVE_CHARACTER character @@ -556,17 +568,17 @@ Property lists are a mechanism for modifying the default behavior when creating more information on property lists see the \ref LBPropsList tutorial topic. The following property lists can be specified when creating a dataset: -\li Dataset Creation Property List
+\li Dataset Creation Property List
When creating a dataset, HDF5 allows the user to specify how raw data is organized and/or compressed on disk. This information is stored in a dataset creation property list and passed to the dataset interface. The raw data on disk can be stored contiguously (in the same linear way that it is organized in memory), partitioned into chunks, stored externally, etc. In this tutorial, we use the default dataset creation property list (contiguous storage layout and no compression). For more information about dataset creation property lists, see \ref sec_dataset in the \ref UG. -\li Link Creation Property List
+\li Link Creation Property List
The link creation property list governs creation of the link(s) by which a new dataset is accessed and the creation of any intermediate groups that may be missing. -\li Dataset Access Property List
+\li Dataset Access Property List
Dataset access property lists are properties that can be specified when accessing a dataset. \section secLBDsetCreateSteps Steps to Create a Dataset @@ -766,7 +778,7 @@ To read from or write to a dataset, the #H5Dread and #H5Dwrite routines are used C \code - status = H5Dread (set_id, mem_type_id, mem_space_id, file_space_id, xfer_prp, buf ); + status = H5Dread (set_id, mem_type_id, mem_space_id, file_space_id, xfer_prp, buf); status = H5Dwrite (set_id, mem_type_id, mem_space_id, file_space_id, xfer_prp, buf); \endcode diff --git a/doxygen/dox/LearnBasics2.dox b/doxygen/dox/LearnBasics2.dox index 0df7d9ab620..eccb865fb09 100644 --- a/doxygen/dox/LearnBasics2.dox +++ b/doxygen/dox/LearnBasics2.dox @@ -858,11 +858,45 @@ H5Tinsert (complex_id, "imaginary", HOFFSET(tmp,im), H5T_NATIVE_DOUBLE); \endcode \subsection subsecLBDtypeSpecRef Reference -There are two types of Reference datatypes in HDF5: +There are three types of Reference datatypes in HDF5: +\li \ref subsubsecLBDtypeSpecRefStd \li \ref subsubsecLBDtypeSpecRefObj \li \ref subsubsecLBDtypeSpecRefDset -\subsubsection subsubsecLBDtypeSpecRefObj Reference to objects +\subsubsection subsubsecLBDtypeSpecRefStd Standard Reference +HDF5 references allow users to reference existing HDF5 objects as well as selections within datasets. The +original API, now deprecated, was extended in order to add the ability to reference attributes as well as objects in +external files. + +The newer API introduced a single opaque reference type, which not only has the advantage of hiding the internal +representation of references, but it also allows for future extensions to be added more seamlessly. The newer API +introduces a single abstract #H5R_ref_t type as well as attribute references and external references +(i.e., references to objects in an external file). + +A file, group, dataset, named datatype, or attribute may be the target of an object reference. +The object reference is created by +#H5Rcreate_object with the name of an object which may be a file, group, dataset, named datatype, or attribute +and the reference type #H5R_OBJECT. The object does not have to be open to create a reference to it. + +An object reference may also refer to a region (selection) of a dataset. The reference is created +with #H5Rcreate_region. The dataspace for the region can be retrieved with a call to #H5Ropen_region. + +An object reference may also refer to a attribute. The reference is created +with #H5Rcreate_attr. #H5Ropen_attr can be used to open the attribute by returning an identifier +to the attribute just as if #H5Aopen has been called. + +An object reference can be accessed by a call to #H5Ropen_object. + +When the reference is to a dataset or dataset region, the #H5Ropen_object call returns an +identifier to the dataset just as if #H5Dopen has been called. +When the reference is to an attribute, the #H5Ropen_object call returns an +identifier to the attribute just as if #H5Aopen has been called. + +The reference buffer from the #H5Rcreate_object call must be released by +using #H5Rdestroy to avoid resource leaks and possible HDF5 library shutdown issues. And any identifiers +returned by #H5Ropen_object must be closed with the appropriate close call. + +\subsubsection subsubsecLBDtypeSpecRefObj Reference to objects - Deprecated In HDF5, objects (i.e. groups, datasets, and named datatypes) are usually accessed by name. There is another way to access stored objects -- by reference. @@ -890,7 +924,7 @@ The following steps are involved:
  • Close all objects when the task is complete.
    • -\subsubsection subsubsecLBDtypeSpecRefDset Reference to a dataset region +\subsubsection subsubsecLBDtypeSpecRefDset Reference to a dataset region - Deprecated A dataset region reference points to a dataset selection in another dataset. A reference to the dataset selection (region) is constant for the life of the dataset. diff --git a/doxygen/dox/ViewTools.dox b/doxygen/dox/ViewTools.dox index 828a8e9cc1a..9ae42fe9f40 100644 --- a/doxygen/dox/ViewTools.dox +++ b/doxygen/dox/ViewTools.dox @@ -984,7 +984,164 @@ This dataset is much more complex. Also note that subsetting cannot be done on A See this section for more information on the Array datatype. +\subsubsection subsubsecViewToolsViewDtypes_newref New References +References were reworked in HDF5 1.12.0. The new reference datatype is #H5T_STD_REF. The old reference datatypes are deprecated. +@see sec_reference. + \subsubsection subsubsecViewToolsViewDtypes_objref Object Reference +An Object Reference is a reference to an entire object (attribute, dataset, group, or named datatype). +A dataset with an Object Reference datatype consists of one or more Object References. +An Object Reference dataset can be used as an index to an HDF5 file. + +The /DS1 dataset in the following file (h5ex_t_objref.h5) is an Object Reference dataset. +It contains two references, one to group /G1 and the other to dataset /DS2: +\code +$ h5dump h5ex_t_objref.h5 +HDF5 "h5ex_t_objref.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_REFERENCE { H5T_STD_REF } + DATASPACE SIMPLE { ( 2 ) / ( 2 ) } + DATA { + GROUP "h5ex_t_objref.h5/G1" + DATASET "h5ex_t_objref.h5/DS2" + DATA { + } + } + } + DATASET "DS2" { + DATATYPE H5T_STD_I32LE + DATASPACE NULL + DATA { + } + } + GROUP "G1" { + } +} +} +\endcode + +\subsubsection subsubsecViewToolsViewDtypes_regref Region Reference +A Region Reference is a reference to a selection within a dataset. A selection can be either +individual elements or a hyperslab. In h5dump you will see the name of the dataset along with +the elements or slab that is selected. A dataset with a Region Reference datatype consists of +one or more Region References. + +An example of a Region Reference dataset (h5ex_t_regref.h5) can be found on the +\ref ExAPI page, +under Datatypes. If you examine this dataset with h5dump you will see that /DS1 is a +Region Reference dataset as indicated by its datatype, highlighted in bold below: +\code +$ h5dump h5ex_t_regref.h5 +HDF5 "h5ex_t_regref.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_REFERENCE { H5T_STD_REF } + DATASPACE SIMPLE { ( 2 ) / ( 2 ) } + DATA { + DATASET "h5ex_t_regref.h5/DS2"{ + REGION_TYPE POINT (0,1), (2,11), (1,0), (2,4) + DATATYPE H5T_STD_I8LE + DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) } + } + DATASET "h5ex_t_regref.h5/DS2" { + REGION_TYPE BLOCK (0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), + (2,11)-(2,13) + DATATYPE H5T_STD_I8LE + DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) } + } + } + } + DATASET "DS2" { + DATATYPE H5T_STD_I8LE + DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) } + DATA { + (0,0): 84, 104, 101, 32, 113, 117, 105, 99, 107, 32, 98, 114, 111, 119, + (0,14): 110, 0, + (1,0): 102, 111, 120, 32, 106, 117, 109, 112, 115, 32, 111, 118, 101, + (1,13): 114, 32, 0, + (2,0): 116, 104, 101, 32, 53, 32, 108, 97, 122, 121, 32, 100, 111, 103, + (2,14): 115, 0 + } + } +} +} +\endcode + +It contains two Region References: +\li A selection of four individual elements in dataset /DS2 : (0,1), (2,11), (1,0), (2,4) +See the #H5Sselect_elements API in the \ref UG for information on selecting individual elements. +\li A selection of these blocks in dataset /DS2 : (0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13) +See the #H5Sselect_hyperslab API in the \ref UG for how to do hyperslab selection. + +If you look at the code that creates the dataset (h5ex_t_regref.c) you will see that the +first reference is created with these calls: +\code + status = H5Sselect_elements (space, H5S_SELECT_SET, 4, coords[0]); + status = H5Rcreate_region(file, DATASET2, space, H5P_DEFAULT, &wdata[0]); +\endcode + +where the buffer containing the coordinates to select is: +\code + coords[4][2] = { {0, 1}, + {2, 11}, + {1, 0}, + {2, 4} }, +\endcode + +The second reference is created by calling, +\code + status = H5Sselect_hyperslab (space, H5S_SELECT_SET, start, stride, count, block); + status = H5Rcreate_region(file, DATASET2, space, H5P_DEFAULT, &wdata[1]); +\endcode +where start, stride, count, and block have these values: +\code + start[2] = {0, 0}, + stride[2] = {2, 11}, + count[2] = {2, 2}, + block[2] = {1, 3}; +\endcode + +These start, stride, count, and block values will select the elements shown in bold in the dataset: +\code +84 104 101 32 113 117 105 99 107 32 98 114 111 119 110 0 +102 111 120 32 106 117 109 112 115 32 111 118 101 114 32 0 +116 104 101 32 53 32 108 97 122 121 32 100 111 103 115 0 +\endcode + +If you use h5dump to select a subset of dataset +/DS2 with these start, stride, count, and block values, you will see that the same elements are selected: +\code +$ h5dump -d "/DS2" -s "0,0" -S "2,11" -c "2,2" -k "1,3" h5ex_t_regref.h5 +HDF5 "h5ex_t_regref.h5" { +DATASET "/DS2" { + DATATYPE H5T_STD_I8LE + DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) } + SUBSET { + START ( 0, 0 ); + STRIDE ( 2, 11 ); + COUNT ( 2, 2 ); + BLOCK ( 1, 3 ); + DATA { + (0,0): 84, 104, 101, 114, 111, 119, + (2,0): 116, 104, 101, 100, 111, 103 + } + } +} +} +\endcode + +NOTE that you must release the references created in the code with the #H5Rdestroy API. +\code + status = H5Rdestroy(&wdata[0]); + status = H5Rdestroy(&wdata[1]); +\endcode + +For more information on selections, see the tutorial topic on +@ref LBDsetSubRW. Also see the +\ref secViewToolsViewSub tutorial topic on using h5dump to view a subset. + +\subsubsection subsubsecViewToolsViewDtypes_depr_objref Deprecated Object Reference An Object Reference is a reference to an entire object (dataset, group, or named datatype). A dataset with an Object Reference datatype consists of one or more Object References. An Object Reference dataset can be used as an index to an HDF5 file. @@ -1014,7 +1171,7 @@ GROUP "/" { } \endcode -\subsubsection subsubsecViewToolsViewDtypes_regref Region Reference +\subsubsection subsubsecViewToolsViewDtypes_depr_regref Deprecated Region Reference A Region Reference is a reference to a selection within a dataset. A selection can be either individual elements or a hyperslab. In h5dump you will see the name of the dataset along with the elements or slab that is selected. A dataset with a Region Reference datatype consists of @@ -1057,7 +1214,6 @@ It contains two Region References: See the #H5Sselect_elements API in the \ref UG for information on selecting individual elements. \li A selection of these blocks in dataset /DS2 : (0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13) See the #H5Sselect_hyperslab API in the \ref UG for how to do hyperslab selection. - If you look at the code that creates the dataset (h5ex_t_regref.c) you will see that the first reference is created with these calls: diff --git a/fortran/src/H5Fff.F90 b/fortran/src/H5Fff.F90 index 0c8b1d84099..dbd1c809bd5 100644 --- a/fortran/src/H5Fff.F90 +++ b/fortran/src/H5Fff.F90 @@ -427,7 +427,7 @@ END SUBROUTINE h5funmount_f !! !! \brief Opens HDF5 file. !! -!! \param name Name of the file to acecss. +!! \param name Name of the file to access. !! \param access_flags File access flags. Allowable values are: !! \li H5F_ACC_RDWR_F !! \li H5F_ACC_RDONLY_F diff --git a/hl/src/H5DOpublic.h b/hl/src/H5DOpublic.h index 5054178846b..661ca7a2abe 100644 --- a/hl/src/H5DOpublic.h +++ b/hl/src/H5DOpublic.h @@ -17,7 +17,7 @@ extern "C" { #endif -/** \page H5DO_UG The HDF5 High Level Optimizations +/** \page H5DO_UG HDF5 High Level Optimizations * @todo Under Construction */ diff --git a/hl/src/H5DSpublic.h b/hl/src/H5DSpublic.h index edbebdbaf28..4afe51180f9 100644 --- a/hl/src/H5DSpublic.h +++ b/hl/src/H5DSpublic.h @@ -30,7 +30,7 @@ typedef herr_t (*H5DS_iterate_t)(hid_t dset, unsigned dim, hid_t scale, void *vi extern "C" { #endif -/** \page H5DS_UG The HDF5 High Level Dimension Scales +/** \page H5DS_UG HDF5 High Level Dimension Scales * @todo Under Construction */ diff --git a/hl/src/H5IMpublic.h b/hl/src/H5IMpublic.h index 0ba9d648cff..bf219b73e46 100644 --- a/hl/src/H5IMpublic.h +++ b/hl/src/H5IMpublic.h @@ -17,7 +17,7 @@ extern "C" { #endif -/** \page H5IM_UG The HDF5 High Level Images +/** \page H5IM_UG HDF5 High Level Images * @todo Under Construction */ diff --git a/hl/src/H5LTpublic.h b/hl/src/H5LTpublic.h index 343f5272453..18f7502209f 100644 --- a/hl/src/H5LTpublic.h +++ b/hl/src/H5LTpublic.h @@ -34,7 +34,7 @@ typedef enum H5LT_lang_t { extern "C" { #endif -/** \page H5LT_UG The HDF5 High Level Lite +/** \page H5LT_UG HDF5 High Level Lite * @todo Under Construction */ diff --git a/hl/src/H5PTpublic.h b/hl/src/H5PTpublic.h index 3016e77ba60..607e385c5c7 100644 --- a/hl/src/H5PTpublic.h +++ b/hl/src/H5PTpublic.h @@ -17,7 +17,7 @@ extern "C" { #endif -/** \page H5PT_UG The HDF5 High Level Packet Table +/** \page H5PT_UG HDF5 High Level Packet Table * @todo Under Construction */ diff --git a/hl/src/H5TBpublic.h b/hl/src/H5TBpublic.h index 42585cf012f..dbeb330a1db 100644 --- a/hl/src/H5TBpublic.h +++ b/hl/src/H5TBpublic.h @@ -17,7 +17,7 @@ extern "C" { #endif -/** \page H5TB_UG The HDF5 High Level Table +/** \page H5TB_UG HDF5 High Level Table * @todo Under Construction */ diff --git a/src/H5Dmodule.h b/src/H5Dmodule.h index e791f7cf00e..26e748ce1a0 100644 --- a/src/H5Dmodule.h +++ b/src/H5Dmodule.h @@ -67,17 +67,21 @@ * The dataset does not have to open to be linked or unlinked. * * \subsubsection subsubsec_dataset_intro_obj Object Reference - * A dataset may be the target of an object reference. The object reference is created by - * #H5Rcreate with the name of an object which may be a dataset and the reference type + * A file, group, dataset, named datatype, or attribute may be the target of an object reference. + * The object reference is created by + * #H5Rcreate_object with the name of an object which may be a dataset and the reference type * #H5R_OBJECT. The dataset does not have to be open to create a reference to it. * * An object reference may also refer to a region (selection) of a dataset. The reference is created - * with #H5Rcreate and a reference type of #H5R_DATASET_REGION. + * with #H5Rcreate_region. * - * An object reference can be accessed by a call to #H5Rdereference. When the reference is to a - * dataset or dataset region, the #H5Rdereference call returns an identifier to the dataset just as if + * An object reference can be accessed by a call to #H5Ropen_object. When the reference is to a + * dataset or dataset region, the #H5Ropen_object call returns an identifier to the dataset just as if * #H5Dopen has been called. * + * The reference buffer from the #H5Rcreate_object call must be released by + * using #H5Rdestroy to avoid resource leaks and possible HDF5 library shutdown issues. + * * \subsubsection subsubsec_dataset_intro_attr Adding Attributes * A dataset may have user-defined attributes which are created with #H5Acreate and accessed * through the @ref H5A API. To create an attribute for a dataset, the dataset must be open, and the diff --git a/src/H5ESmodule.h b/src/H5ESmodule.h index f128feeab0e..f63852db384 100644 --- a/src/H5ESmodule.h +++ b/src/H5ESmodule.h @@ -25,7 +25,7 @@ #define H5_MY_PKG H5ES #define H5_MY_PKG_ERR H5E_EVENTSET -/** \page H5ES_UG The HDF5 Event Set +/** \page H5ES_UG HDF5 Event Set * @todo Under Construction * * \section sec_async The HDF5 Event Set Interface diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h index 8a65d17ae87..5cb4a05dd7f 100644 --- a/src/H5Fmodule.h +++ b/src/H5Fmodule.h @@ -25,7 +25,7 @@ #define H5_MY_PKG H5F #define H5_MY_PKG_ERR H5E_FILE -/** \page H5F_UG The HDF5 File +/** \page H5F_UG HDF5 File * * \section sec_file The HDF5 File * \subsection subsec_file_intro Introduction diff --git a/src/H5Imodule.h b/src/H5Imodule.h index e6828506d1e..f8924d3df62 100644 --- a/src/H5Imodule.h +++ b/src/H5Imodule.h @@ -25,7 +25,7 @@ #define H5_MY_PKG H5I #define H5_MY_PKG_ERR H5E_ID -/** \page H5I_UG The HDF5 Identifiers +/** \page H5I_UG HDF5 Identifiers * @todo Under Construction */ diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h index 7ab67da8138..f29aa5c50c0 100644 --- a/src/H5Lmodule.h +++ b/src/H5Lmodule.h @@ -25,7 +25,7 @@ #define H5_MY_PKG H5L #define H5_MY_PKG_ERR H5E_LINK -/** \page H5L_UG The HDF5 Links +/** \page H5L_UG HDF5 Links * @todo Under Construction */ diff --git a/src/H5Mmodule.h b/src/H5Mmodule.h index 920ec3d1585..375399751b5 100644 --- a/src/H5Mmodule.h +++ b/src/H5Mmodule.h @@ -26,11 +26,11 @@ #define H5_MY_PKG_ERR H5E_MAP /** - * \page H5M_UG The HDF5 VOL Data Mapping + * \page H5M_UG HDF5 VOL Data Mapping * \Bold{The HDF5 Data Mapping can only be used with the HDF5 VOL connectors that * implement map objects.} The native HDF5 library does not support this feature. * - * \section sec_map The HDF5 Map Object + * \section sec_map HDF5 Map Object * * \todo Describe the map life cycle. * diff --git a/src/H5Omodule.h b/src/H5Omodule.h index c3c3496bf32..1c1278a0e8a 100644 --- a/src/H5Omodule.h +++ b/src/H5Omodule.h @@ -25,7 +25,7 @@ #define H5_MY_PKG H5O #define H5_MY_PKG_ERR H5E_OHDR -/** \page H5O_UG The HDF5 Objects +/** \page H5O_UG HDF5 Objects * @todo Under Construction */ diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h index cccdf6ef506..f034e7c6631 100644 --- a/src/H5PLmodule.h +++ b/src/H5PLmodule.h @@ -26,7 +26,7 @@ #define H5_MY_PKG H5PL #define H5_MY_PKG_ERR H5E_PLUGIN -/** \page H5PL_UG The HDF5 Plugins +/** \page H5PL_UG HDF5 Plugins * * \section sec_filter_plugins HDF5 Filter Plugins * diff --git a/src/H5Rmodule.h b/src/H5Rmodule.h index 5e3affbfabc..443c4746d71 100644 --- a/src/H5Rmodule.h +++ b/src/H5Rmodule.h @@ -24,8 +24,372 @@ #define H5_MY_PKG H5R #define H5_MY_PKG_ERR H5E_REFERENCE -/** \page H5R_UG The HDF5 References - * @todo Under Construction +/** \page H5R_UG HDF5 References + * + * \section sec_reference HDF5 References + * HDF5 references allow users to reference existing HDF5 objects (file, group, dataset, named datatype, or + * attribute) as well as selections within datasets. + * + * The original API, now deprecated, was extended in order to add the ability to reference attributes as well + * as objects in external files. Additionally, there were some inherent limitations within the older API that + * restricted its use with virtual object layer (VOL) connectors, which do not necessarily follow HDF5’s + * native file format. + * + * The newer API introduced a single opaque reference type, which not only has the advantage of hiding the + * internal representation of references, but it also allows for future extensions to be added more + * seamlessly. + * + * \subsection subsec_reference_intro Introduction + * The deprecated HDF5 reference API only allowed users to create references to HDF5 objects (groups, + * datasets) and regions within a dataset. There were some limitations: it defined two separate reference + * types #hobj_ref_t and #hdset_reg_ref_t; the former directly mapped to an #haddr_t type that did not allow + * for external references, while the latter mapped to an HDF5 global heap entry, which was specific to native + * HDF5 and was created and written to the file when the reference was created. This prevented users from + * creating region references when the file is opened read-only, it was also not suitable for use outside of + * native HDF5 files. The newer API addressed these limitations by introducing a single abstract #H5R_ref_t + * type as well as missing reference types such as attribute references and external references (i.e., + * references to objects in an external file). + * + * \subsection subsec_reference_dep Deprecated API + * There is no support for attribute references; references are only valid within the + * container that they reference; the size of the reference types are tied to the definition of an haddr_t or + * an entry in the file’s global heap, which only exists in native HDF5. + * + * \subsubsection subsubsec_reference_limit Limitations + * \li The #H5Rcreate signature forces users to constantly pass (#H5I_INVALID_HID) as a space_id, in the case + * where the reference type is not a region reference. + * \li The size of region + * references was defined as the size required to encode a global heap ID, this definition forces + * references to be written to the file at the time of their creation, hence preventing them to be created + * from a file that is opened read-only (e.g, when creating references to a file that one does not want + * to/cannot modify). + * + * \subsubsection subsubsec_reference_old_API Deprecated Methods + * The original API before hdf5 1.12.0 is defined below: + * \code + * // Deprecated reference buffer sizes that are kept for backward compatibility + * #define H5R_OBJ_REF_BUF_SIZE sizeof(haddr_t) + * #define H5R_DSET_REG_REF_BUF_SIZE (sizeof(haddr_t) + 4) + * + * // Reference types + * typedef enum H5R_type_t { + * H5R_BADTYPE = (-1), // Invalid Reference Type + * H5R_OBJECT, // Object reference + * H5R_DATASET_REGION, // Dataset Region Reference + * H5R_MAXTYPE // Highest type (Invalid as true type) + * } H5R_type_t; + * + * // Object reference structure for user's code + * // This needs to be large enough to store largest haddr_t on a worst case + * // machine (8 bytes currently). + * typedef haddr_t hobj_ref_t; + * + * // Dataset Region reference structure for user's code + * // (Buffer to store heap ID and index) + * // This needs to be large enough to store largest haddr_t in a worst case + * // machine (8 bytes currently) plus an int + * typedef unsigned char hdset_reg_ref_t[H5R_DSET_REG_REF_BUF_SIZE]; + * + * // Prototypes + * herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id); + * hid_t H5Rdereference2(hid_t obj_id, hid_t oapl_id, H5R_type_t ref_type, const void *ref); + * hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref); + * herr_t H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *_ref, H5O_type_t *obj_type); + * ssize_t H5Rget_name(hid_t loc_id, H5R_type_t ref_type, const void *ref, char *name , size_t size); + * \endcode + * + * \subsection subsec_reference_new New API + * The current API is defined below: + * \code + * // Deprecated reference buffer sizes that are kept for backward compatibility + * #define H5R_OBJ_REF_BUF_SIZE sizeof(haddr_t) + * #define H5R_DSET_REG_REF_BUF_SIZE (sizeof(haddr_t) + 4) + * + * // Default reference buffer size. + * #define H5R_REF_BUF_SIZE (64) + * + * // Reference types allowed. + * typedef enum { + * H5R_BADTYPE = (-1), // Invalid reference type + * H5R_OBJECT1 = 0, // Backward compatibility (object) + * H5R_DATASET_REGION1 = 1, // Backward compatibility (region) + * H5R_OBJECT2 = 2, // Object reference + * H5R_DATASET_REGION2 = 3, // Region reference + * H5R_ATTR = 4, // Attribute Reference + * H5R_MAXTYPE = 5 // Highest type (invalid) + * } H5R_type_t; + * + * // Deprecated object reference type that is used with deprecated reference APIs. + * // This type can only be used with the "native" HDF5 VOL connector. + * typedef haddr_t hobj_ref_t; + * + * // Deprecated dataset region reference type that is used with deprecated reference APIs. + * // This type can only be used with the "native" HDF5 VOL connector. + * typedef struct { + * uint8_t __data[H5R_DSET_REG_REF_BUF_SIZE]; + * } hdset_reg_ref_t; + * + * // Opaque reference type. The same reference type is used for object, + * // dataset region and attribute references. This is the type that + * // should always be used with the current reference API. + * typedef struct { + * union { + * uint8_t __data[H5R_REF_BUF_SIZE]; // opaque data + * int64_t align; // ensures alignment + * } u; + * } H5R_ref_t; + * + * // Constructors + * herr_t H5Rcreate_object(hid_t loc_id, const char *name, H5R_ref_t *ref_ptr); + * herr_t H5Rcreate_region(hid_t loc_id, const char *name, hid_t space_id, H5R_ref_t *ref_ptr); + * herr_t H5Rcreate_attr(hid_t loc_id, const char *name, const char *attr_name, H5R_ref_t *ref_ptr); + * herr_t H5Rdestroy(H5R_ref_t *ref_ptr); + * + * // Info + * H5R_type_t H5Rget_type(const H5R_ref_t *ref_ptr); + * htri_t H5Requal(const H5R_ref_t *ref1_ptr, const H5R_ref_t *ref2_ptr); + * herr_t H5Rcopy(const H5R_ref_t *src_ref_ptr, H5R_ref_t *dst_ref_ptr); + * + * // Dereference + * hid_t H5Ropen_object(const H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id); + * hid_t H5Ropen_region(const H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id); + * hid_t H5Ropen_attr(const H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id); + * + * // Get type + * herr_t H5Rget_obj_type3(const H5R_ref_t *ref_ptr, hid_t rapl_id, H5O_type_t *obj_type); + * + * // Get name + * ssize_t H5Rget_file_name(const H5R_ref_t *ref_ptr, char *name, size_t size); + * ssize_t H5Rget_obj_name(const H5R_ref_t *ref_ptr, hid_t rapl_id, char *name, size_t size); + * ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t size); + * \endcode + * + * References can be stored and retrieved from a file by invoking the #H5Dwrite and #H5Dread functions + * with this single predefined type: #H5T_STD_REF. + * + * The advantage of a single type is that it becomes easier for users to mix references of different types. It + * is also more in line with the opaque type now defined for references. Note that when reading references + * back from a file, the library may, in consequence of this new design, allocate memory for each of these + * references. To release the memory, one must either call #H5Rdestroy on each of the references or, for + * convenience, call the new #H5Treclaim function on the buffer that contains the array of references (type + * can be compound type, array). + * + * As mentioned, instead of having separate routines for both vlen and reference types, we unify the existing: + * \code + * herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf); + * \endcode + * to + * \code + * herr_t H5Treclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf); + * \endcode + * + * \subsection subsec_reference_compat API Compatibility + * To preserve compatibility with applications and middleware libraries that have been using the existing + * reference API, we keep the existing #H5Rcreate, #H5Rdereference2, #H5Rget_region, + * #H5Rget_obj_type2 and #H5Rget_name routines, but moved to the deprecated + * API list of functions. + * + * It is important to note though that these routines only support the original reference types, noted as + * #H5R_OBJECT1 and #H5R_DATASET_REGION1 respectively. Any other reference type passed to these routines + * will return an error. For convenience and compatibility with previous versions of the library we define + * both #H5R_OBJECT and #H5R_DATASET_REGION to map to the original reference types \code + * // Versions for compatibility + * #define H5R_OBJECT H5R_OBJECT1 + * #define H5R_DATASET_REGION H5R_DATASET_REGION1 + * \endcode + * + * When creating and accessing references through these deprecated routines, users are still expected to use + * the datatypes which describe the #hobj_ref_t and #hdset_reg_ref_t types, #H5T_STD_REF_OBJ and + * #H5T_STD_REF_DSETREG. + * + * One important aspect of these changes is to ensure that previously written data can still be readable after + * those revisions and that new files produced will not create any undefined behavior when used with previous + * versions of the library. Backward as well as forward compatibility is summarized in the table: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
    VersionOld File Format/Old APIOld File Format/New APINew File Format/Old + * APINew File Format/New API
    < 1.12.0No changeN/ADatatype version bump prevents from reading unknown + * reference typesN/A
    ≥ 1.12.0Read and write references through old datatypes and use #hobj_ref_t and #hdset_reg_ref_t typesRead and write using #H5T_STD_REF to convert to new #H5R_ref_t typeCannot use old API with new reference typesCan use opaque #H5R_ref_t type for all reference types
    + * + * Because previous library versions do not have a way of detecting when new unknown references types are + * read, we have to increment the global version of the datatypes, so that early detection can be done and the + * appropriate error is returned to the user. For versions prior to this change, the library will return an + * error when the datatype encountered has a version number greater than the currently supported version. + * Also, to prevent datatype version changes in the future, all library branches are now patched to check for + * unknown reference types. + * + * When reading old data with the new library version, one can either keep using the #H5T_STD_REF_OBJ + * and #H5T_STD_REF_DSETREG datatypes, which can be queried when opening a dataset, for example using + * #H5Dget_type, or use the #H5T_STD_REF datatype, which will trigger automatic type conversion. The + * #H5T_STD_REF_OBJ and #H5T_STD_REF_DSETREG datatypes require the use of the respective #hobj_ref_t + * and #hdset_reg_ref_t types, which can only be used with the old API functions. These types do not embed + * all the required information to be simply cast to an #H5R_ref_t type. When an #H5R_ref_t type is desired, + * the #H5T_STD_REF datatype must be used, allowing old reference data to be used with the new API. + * + * \subsection subsec_reference_example Usage Examples + * + * \subsubsection subsubsec_reference_example_new External References + * The example below illustrates the use of the new API with files that are opened read-only. Created + * references to the objects in that file are stored into a separate file, and accessed from that file, + * without the user explicitly opening the original file that was referenced. \code #include + * + * #include "hdf5.h" + * #include + * + * #define H5FILE_NAME1 "refer_extern1.h5" + * #define H5FILE_NAME2 "refer_extern2.h5" + * + * #define NDIMS 1 // Number of dimensions + * #define BUF_SIZE 4 // Size of example buffer + * #define NREFS 1 // Number of references + * + * int main(void) { + * hid_t file1, dset1, space1; + * hsize_t dset1_dims[NDIMS] = { BUF_SIZE }; + * int dset_buf[BUF_SIZE]; + * + * hid_t file2, dset2, space2; + * hsize_t dset2_dims[NDIMS] = { NREFS }; + * H5R_ref_t ref_buf[NREFS] = { 0 }; + * H5O_type_t obj_type; + * int i; + * + * for (i = 0; i < BUF_SIZE; i++) + * dset_buf[i] = i; + * + * // Create file with one dataset and close it + * file1 = H5Fcreate(H5FILE_NAME1, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + * space1 = H5Screate_simple(NDIMS, dset1_dims, NULL); + * dset1 = H5Dcreate2(file1, "dataset1", H5T_NATIVE_INT, space1, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT); + * H5Dwrite(dset1, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, dset_buf); + * H5Dclose(dset1); + * H5Sclose(space1); + * H5Fclose(file1); + * + * // Create reference to dataset1 in "refer_extern1.h5" + * file1 = H5Fopen(H5FILE_NAME1, H5F_ACC_RDONLY, H5P_DEFAULT); + * H5Rcreate_object(file1, "dataset1", &ref_buf[0]); + * H5Fclose(file1); + * + * // Store reference in dataset in separate file "refer_extern2.h5" + * file2 = H5Fcreate(H5FILE_NAME2, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + * space2 = H5Screate_simple(NDIMS, dset2_dims, NULL); + * dset2 = H5Dcreate2(file2, "references", H5T_STD_REF, space2, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT); + * H5Dwrite(dset2, H5T_STD_REF, H5S_ALL, H5S_ALL, H5P_DEFAULT, ref_buf); + * H5Dclose(dset2); + * H5Sclose(space2); + * H5Fclose(file2); + * H5Rdestroy(&ref_buf[0]); + * + * // Read reference back from "refer_extern2.h5" + * file2 = H5Fopen(H5FILE_NAME2, H5F_ACC_RDONLY, H5P_DEFAULT); + * dset2 = H5Dopen2(file2, "references", H5P_DEFAULT); + * H5Dread(dset2, H5T_STD_REF, H5S_ALL, H5S_ALL, H5P_DEFAULT, ref_buf); + * H5Dclose(dset2); + * H5Fclose(file2); + * + * // Access reference and read dataset data without opening original file + * assert(H5Rget_type((const H5R_ref_t *)&ref_buf[0]) == H5R_OBJECT2); + * H5Rget_obj_type3((const H5R_ref_t *)&ref_buf[0], H5P_DEFAULT, &obj_type); + * assert(obj_type == H5O_TYPE_DATASET); + * dset1 = H5Ropen_object((const H5R_ref_t *)&ref_buf[0], H5P_DEFAULT, H5P_DEFAULT); + * H5Dread(dset1, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, dset_buf); + * H5Dclose(dset1); + * H5Rdestroy(&ref_buf[0]); + * + * for (i = 0; i < BUF_SIZE; i++) + * assert(dset_buf[i] == i); + * + * return 0; + * } + * \endcode + * + * \subsubsection subsubsec_reference_example_old Backward Compatibility and New API + * The example below illustrates the use of the new API with a file that was written using the old-style + * reference API, showing how one can take advantage of the automatic type conversion from old reference type + * to new reference type. + * \code #include + * + * #include "hdf5.h" + * #include + * + * #define H5FILE_NAME "refer_deprec.h5" + * + * #define NDIMS 1 // Number of dimensions + * #define BUF_SIZE 4 // Size of example buffer + * #define NREFS 1 // Number of references + * + * int main(void) { + * hid_t file1, dset1, space1; + * hsize_t dset1_dims[NDIMS] = { BUF_SIZE }; + * int dset_buf[BUF_SIZE]; + * + * hid_t dset2, space2; + * hsize_t dset2_dims[NDIMS] = { NREFS }; + * hobj_ref_t ref_buf[NREFS] = { 0 }; + * H5R_ref_t new_ref_buf[NREFS] = { 0 }; + * H5O_type_t obj_type; + * int i; + * + * for (i = 0; i < BUF_SIZE; i++) + * dset_buf[i] = i; + * + * // Create file with one dataset and close it + * file1 = H5Fcreate(H5FILE_NAME, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + * + * space1 = H5Screate_simple(NDIMS, dset1_dims, NULL); + * dset1 = H5Dcreate2(file1, "dataset1", H5T_NATIVE_INT, space1, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT); + * H5Dwrite(dset1, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, dset_buf); + * H5Dclose(dset1); + * H5Sclose(space1); + * + * // Create reference to dataset1 with deprecated API + * // (reminder: there is no destroy call for those references) + * H5Rcreate(&ref_buf[0], file1, "dataset1", H5R_OBJECT, H5I_INVALID_HID); + * + * // Store reference in separate dataset using deprecated reference type + * space2 = H5Screate_simple(NDIMS, dset2_dims, NULL); + * dset2 = H5Dcreate2(file1, "references", H5T_STD_REF_OBJ, space2, H5P_DEFAULT, H5P_DEFAULT, + * H5P_DEFAULT); + * H5Dwrite(dset2, H5T_STD_REF_OBJ, H5S_ALL, H5S_ALL, H5P_DEFAULT, ref_buf); H5Dclose(dset2); + * H5Sclose(space2); + * H5Fclose(file1); + * + * // Read reference from file using new reference type + * file1 = H5Fopen(H5FILE_NAME, H5F_ACC_RDONLY, H5P_DEFAULT); + * dset2 = H5Dopen2(file1, "references", H5P_DEFAULT); + * H5Dread(dset2, H5T_STD_REF, H5S_ALL, H5S_ALL, H5P_DEFAULT, new_ref_buf); + * H5Dclose(dset2); + * + * // Access reference and read dataset data through new API + * assert(H5Rget_type((const H5R_ref_t *)&new_ref_buf[0]) == H5R_OBJECT2); + * H5Rget_obj_type3((const H5R_ref_t *)&new_ref_buf[0], H5P_DEFAULT, &obj_type); + * assert(obj_type == H5O_TYPE_DATASET); + * dset1 = H5Ropen_object((const H5R_ref_t *)&new_ref_buf[0], H5P_DEFAULT, H5P_DEFAULT); + * H5Dread(dset1, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, dset_buf); + * H5Dclose(dset1); + * H5Rdestroy(&new_ref_buf[0]); + * + * for (i = 0; i < BUF_SIZE; i++) + * assert(dset_buf[i] == i); + * return 0; + * } + * \endcode + * + * */ /** diff --git a/src/H5Smodule.h b/src/H5Smodule.h index d212d5dbf2c..2dc8fe127d6 100644 --- a/src/H5Smodule.h +++ b/src/H5Smodule.h @@ -974,7 +974,33 @@ * * This section is under construction. * - * \subsection subsec_dataspace_refer References to Dataset Regions + * \subsection subsec_dataspace_refer References + * + * Another use of selections is to store a reference to a region of a dataset in the file or an external file. + An HDF5 object reference + * object is a pointer to an object (attribute, dataset, group, or committed datatype) in the file or an + external file. A selection can + * be used to create a pointer to a set of selected elements of a dataset, called a region reference. The + * selection can be either a point selection or a hyperslab selection. + * + * A region reference is an object maintained by the HDF5 Library. The region reference can be stored in a + * dataset or attribute, and then read. The dataset or attribute is defined to have the special datatype, + * #H5T_STD_REF. + * + * To discover the elements and/or read the data, the region reference can be dereferenced to obtain the + * identifiers for the dataset and dataspace. + * + * For more information, \see subsubsec_datatype_other_refs. + * + * \subsubsection subsubsec_dataspace_refer_use Example Uses for Region References + * + * \subsubsection subsubsec_dataspace_refer_create Creating References to Regions + * + * \subsubsection subsubsec_dataspace_refer_read Reading References to Regions + * + * \subsection subsec_dataspace_deprecated_refer Deprecated References to Dataset Regions + * The API described in this section was deprecated since HDF5 1.12.0. Shown are + * examples and usage in use by applications written before 1.12.0. * * Another use of selections is to store a reference to a region of a dataset. An HDF5 object reference * object is a pointer to an object (dataset, group, or committed datatype) in the file. A selection can @@ -992,7 +1018,7 @@ * * For more information, \see subsubsec_datatype_other_refs. * - * \subsubsection subsubsec_dataspace_refer_use Example Uses for Region References + * \subsubsection subsubsec_dataspace_deprecated_refer_use Deprecated Example Uses for Region References * * Region references are used to implement stored pointers to data within a dataset. For example, features * in a large dataset might be indexed by a table. See the figure below. This table could be stored as an @@ -1016,7 +1042,7 @@ * * * - * \subsubsection subsubsec_dataspace_refer_create Creating References to Regions + * \subsubsection subsubsec_dataspace_deprecated_refer_create Deprecated Creating References to Regions * * To create a region reference: * \li 1. Create or open the dataset that contains the region @@ -1043,7 +1069,7 @@ * and a reference is created using \ref H5Rcreate(). The call to \ref H5Rcreate() specifies the file, * dataset, and the dataspace with selection. * - * Create an array of region references + * Deprecated Create an array of region references * \code * // create an array of 4 region references * hdset_reg_ref_t ref[4]; @@ -1085,7 +1111,7 @@ * When all the references are created, the array of references is written to the dataset R1. The * dataset is declared to have datatype #H5T_STD_REF_DSETREG. See the example below. * - * Write the array of references to a dataset + * Deprecated Write the array of references to a dataset * \code * Hsize_t dimsr[1]; * dimsr[0] = 4; @@ -1105,7 +1131,7 @@ * \li The dataset must exist in the file when the reference is created; #H5Rcreate * \li The target dataset must be in the same file as the stored reference * - * \subsubsection subsubsec_dataspace_refer_read Reading References to Regions + * \subsubsection subsubsec_dataspace_refer_deprecated_read Deprecated Reading References to Regions * * To retrieve data from a region reference, the reference must be read from the file, and then the data can * be retrieved. The steps are: @@ -1127,7 +1153,7 @@ * \li The target dataset must be present and accessible in the file * \li The selection must be a valid selection for the dataset * - * Read an array of region references; read from the first selection + * Deprecated Read an array of region references; read from the first selection * \code * dsetr_id = H5Dopen (file_id, "R1", H5P_DEFAULT); * status = H5Dread(dsetr_id, H5T_STD_REF_DSETREG, H5S_ALL, H5S_ALL, H5P_DEFAULT, ref_out); diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h index 35e748bac3f..fd2a278fd22 100644 --- a/src/H5Tmodule.h +++ b/src/H5Tmodule.h @@ -598,10 +598,10 @@ * * * - * #H5T_STD_REF_OBJ + * #H5T_STD_REF * * - * Reference to an entire object in a file + * Reference to an object in a file * * * @@ -2943,8 +2943,63 @@ filled according to the value of this property. The padding can be: * \endcode * * \subsubsection subsubsec_datatype_other_refs Reference + * In HDF5, objects (groups, datasets, attributes, and committed datatypes) are usually accessed by name. + * There is another way to access stored objects - by reference. Before HDF5 1.12.0, there were only two + * reference datatypes: object reference and region reference. Since 1.12.0, attribute references and + * external references were added. And all references can be stored and retrieved from a file by invoking + * the #H5Dwrite and #H5Dread functions with a single predefined type: #H5T_STD_REF. + * + * The first example below shows an example of code that creates + * references to four objects, and then writes the array of object references to a dataset. The second + * example below shows a dataset of datatype reference being read and one of the reference objects + * being dereferenced to obtain an object pointer. + * + * Create object references and write to a dataset + * \code + * dataset = H5Dcreate (fid1, “Dataset3”, H5T_STD_REF, sid1, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT); + * + * // Create reference to dataset + * ret = H5Rcreate_object(fid1,“/Group1/Dataset1”, H5R_OBJECT, &wbuf[0]); + * + * // Create reference to dataset + * ret = H5Rcreate_object(fid1, “/Group1/Dataset2”, H5R_OBJECT, &wbuf[1]); + * + * // Create reference to group + * ret = H5Rcreate_object(fid1, “/Group1”, H5R_OBJECT, &wbuf[2]); + * + * // Create reference to committed datatype + * ret = H5Rcreate_object(fid1, “/Group1/Datatype1”, H5R_OBJECT, &wbuf[3]); + * + * // Write selection to disk + * ret = H5Dwrite(dataset, H5T_STD_REF, H5S_ALL, H5S_ALL, H5P_DEFAULT, wbuf); + * + * // Release buffers + * status = H5Rdestroy(&wdata[0]); + * status = H5Rdestroy(&wdata[1]); + * status = H5Rdestroy(&wdata[2]); + * status = H5Rdestroy(&wdata[3]); + * \endcode + * + * Read a dataset with a reference datatype + * \code + * rbuf = (H5R_ref_t *)malloc(dims[0] * sizeof(H5R_ref_t)); + * + * // Read selection from disk + * ret = H5Dread(dataset, H5T_STD_REF, H5S_ALL, H5S_ALL, H5P_DEFAULT, rbuf); + * + * // Open dataset object + * dset2 = H5Ropen_object(&rbuf[0], H5P_DEFAULT, H5P_DEFAULT); + * + * // Release buffers + * status = H5Rdestroy(&rbuf[0]); + * status = H5Rdestroy(&rbuf[1]); + * status = H5Rdestroy(&rbuf[2]); + * status = H5Rdestroy(&rbuf[3]); + * \endcode + * + * \subsubsection subsubsec_datatype_other_drefs Deprecated Reference * In HDF5, objects (groups, datasets, and committed datatypes) are usually accessed by name. - * There is another way to access stored objects - by reference. There are two reference datatypes: + * There is another way to access stored objects - by reference. There are two deprecated reference datatypes: * object reference and region reference. Object reference objects are created with #H5Rcreate and * other calls (cross reference). These objects can be stored and retrieved in a dataset as elements * with reference datatype. The first example below shows an example of code that creates @@ -3748,6 +3803,7 @@ filled according to the value of this property. The padding can be: * * ::= | |