From a7c84135d3598be3c35b1f8961f6b8e9a27cec52 Mon Sep 17 00:00:00 2001 From: Gerd Heber Date: Mon, 9 Nov 2020 16:52:42 -0600 Subject: App. compatibilty macro outline. --- doxygen/dox/api-compat-macros.dox | 195 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 doxygen/dox/api-compat-macros.dox diff --git a/doxygen/dox/api-compat-macros.dox b/doxygen/dox/api-compat-macros.dox new file mode 100644 index 0000000..239e608 --- /dev/null +++ b/doxygen/dox/api-compat-macros.dox @@ -0,0 +1,195 @@ +/** \page api-compat-macros API Compatibility Macros + \tableofcontents + + \section audience Audience + The target audience for this document has existing applications that use the + HDF5 library, and is considering moving to the latest HDF5 release to take + advantage of the latest library features and enhancements. + + \section compat-issues Compatibility Issues + With each major release of HDF5, such as 1.12 or 1.10, certain compatibility + issues must be considered when migrating applications from an earlier major + release. + + This document describes the approach taken by The HDF Group to help existing + users of HDF5 address compatibility issues in the HDF5 API. + + \section summary Summary and Motivation + In response to new and evolving requirements for the library and data format, + several basic functions have changed since HDF5 was first released. To allow + existing applications to continue to compile and run properly, all versions + of these functions have been retained in the later releases of the HDF5 library. + + Given the scope of changes available with each major release of HDF5, and + recognizing the potentially time-consuming task of editing all the affected + calls in user applications, The HDF Group has created a set of macros that + can be used to flexibly and easily map existing API calls to previous release + functions. We refer to these as the \Emph{API compatibility macros}. + + The HDF Group generally encourages users to update applications to work with + the latest HDF5 library release so that all new features and enhancements are + available to them. At the same time, The HDF Group understands that, under + some circumstances, updating applications may not be feasible or necessary. + The API compatibility macros, described in this document, provide a bridge + from old APIs to new and can be particularly helpful in situations such as these: + + + \section using Understanding and Using the Macros + As part of latest HDF5 release, several functions that existed in previous + versions of the library were updated with new calling parameters and given + new names. The updated versions of the functions have a number (for, e.g., '2') + at the end of the original function name. The original versions of these + functions were retained and renamed to have an earlier number (for, e.g., '1') + at the end of the original function name. + + For example, consider the function \Code{H5Lvisit} in HDF5 release 1.10 + as compared with 1.12: + + + + + + + + + + + + + + + + +
Original function name and signature in 1.10.0 + \Code{herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate_t op, void *op_data)} +
Updated function and signature, introduced in release 1.12.0 + \Code{herr_t H5Lvisit2(hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate2_t op, void *op_data)} +
Original function and signature, renamed in release 1.12.0 + \Code{herr_t H5Lvisit1(hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate1_t op, void *op_data)} +
API compatibility macro, introduced in release 1.12.0 + \Code{H5Lvisit} +

The macro, \Code{H5Lvisit}, will be mapped to either \Code{H5Lvisit1} or + \Code{H5Lvisit2}. The mapping is determined by a combination of the + configuration options use to build the HDF5 library and compile-time + options used to build the application. The calling parameters used with the + \Code{H5Lvisit} compatibility macro should match the number and type of the + function the macros will be mapped to (\Code{H5Lvisit1} or \Code{H5Lvisit2}). +

+

The function names ending in '1' or '2' are referred to as \Emph{versioned names}, + and the corresponding functions are referred to as \Emph{versioned functions}. + For new code development, The HDF Group recommends use of the compatibility macro + mapped to the latest version of the function. The original version of the function + should be considered deprecated and, in general, should not be used when developing + new code. +

+
+ + \section options Compatibility Macro Mapping Options + To determine the mapping for a given API compatibility macro in a given application, + a combination of user-controlled selections, collectively referred to as the + \Emph{compatibility macro mapping options}, is considered in the following sequence: + + + + + + +
+
    +
  1. What compatibility macro configuration option was used to build the HDF5 library? + We refer to this selection as the \Emph{library mapping}.
    2. +
  2. Was a compatibility macro global compile-time option specified when the application + was built? We refer to this (optional) selection as the \Emph{application mapping}. + If an application mapping exists, it overrides the library mapping. + \Emph{(See adjacent notes.)}
    3. +
  3. Were any compatibility macro function-level compile-time options specified when the + application was built? We refer to these (optional) selections as \Emph{function mappings}. + If function mappings exist, they override library and application mappings for the + relevant API compatibility macros. \Emph{(See adjacent notes.)}
    4. +
+ 		+ + + +
+ \Bold{Notes:} An application mapping can map APIs to the same version or to a version + older than the configured library mapping. When the application attempts to map APIs + to a newer version of the API than the library was configured with, it will fail to + "upgrade" the mapping (and may fail silently). + + When it is necessary to "upgrade" the macro mappings from those set in the library mapping, + it must be done at the per-function level, using the function-level mappings. As long as + one does not try to map a function to a version that was compiled out in the library mapping, + individual functions can be upgraded or downgraded freely. +
+
+ + \subsection lib-options Library Mapping Options + When the HDF5 library is built, \Code{configure} flags can be used to control the API + compatibility macro mapping behavior exhibited by the library. This behavior can be + overridden by application and function mappings. One configure flag excludes deprecated + functions from the HDF5 library, making them unavailable to applications linked with the + library. + +
Table 1: Library Mapping Options + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
\Code{configure} flagMacros map to release
(versioned function; \Code{H5Lvisit} shown)		Deprecated functions available?
(\Code{H5Lvisit1})
\Code{--with-default-api-version=v112}
(the default in 1.12)		1.12.x (\Code{H5Lvisit2})yes
\Code{--with-default-api-version=v110}1.10.x (\Code{H5Lvisit1})yes
\Code{--with-default-api-version=v18}1.8.x (\Code{H5Lvisit1})yes
\Code{--with-default-api-version=v16}1.6.x (\Code{H5Lvisit1})yes
\Code{--disable-deprecated-symbols}1.12.x (\Code{H5Lvisit2})no
+
+ Refer to the file \Code{libhdf5.settings} in the directory where the HDF5 library is + installed to determine the \Code{configure} flags used to build the library. In particular, + look for the two lines shown here under \Emph{Features}: + + \Code{Default API mapping: v112} + + \Code{With deprecated public symbols: yes} + + \subsection app-options Application Mapping Options + \subsection fun-options Function Mapping Options + \subsubsection fun-options-112 Function Mapping Options in Releases 1.12.x + \subsubsection fun-options-110 Function Mapping Options in Releases 1.10.x + \subsubsection fun-options-18 Function Mapping Options in Releases 1.8.x + \subsubsection further Further Information + \section macros Compatibility Macros in HDF5 1.6.8 and Later + \section use-case Common Use Case +*/ \ No newline at end of file -- cgit v0.12