diff options
| -rw-r--r-- | doxygen/dox/H5Oget_info_by_name.dox | 18 | ||||
| -rw-r--r-- | doxygen/dox/api-compat-macros.dox | 105 | ||||
| -rw-r--r-- | doxygen/dox/mainpage.dox | 2 |
3 files changed, 102 insertions, 23 deletions
diff --git a/doxygen/dox/H5Oget_info_by_name.dox b/doxygen/dox/H5Oget_info_by_name.dox index 3276c5a..b1b9540 100644 --- a/doxygen/dox/H5Oget_info_by_name.dox +++ b/doxygen/dox/H5Oget_info_by_name.dox @@ -12,9 +12,9 @@ * document closely. * * In HDF5 versions 1.12 and after, #H5Oget_info_by_name is mapped to - * \ref H5Oget_info_by_name3(). In version 1.10 #H5Oget_info_by_name is - * identical to \ref H5Oget_info_by_name1(). - * + * \ref H5Oget_info_by_name3(). In version 1.10 #H5Oget_info_by_name is + * identical to \ref H5Oget_info_by_name1(). + * * Specific compile-time compatibility flags and the resulting * mappings are as follows: * @@ -66,27 +66,27 @@ * </tr> * <tr> * <td></td> - * <td>This change was added to restore the broken API compatibility + * <td>This change was added to restore the broken API compatibility * introduced in HDF5-1.10.3.</td> * </tr> * <tr> * <td>1.10.3</td> - * <td>The function \ref H5Oget_info_by_name() was renamed + * <td>The function \ref H5Oget_info_by_name() was renamed * to \ref H5Oget_info_by_name1.</td> * </tr> * <tr> * <td></td> - * <td>The macro #H5Oget_info_by_name was renamed to + * <td>The macro #H5Oget_info_by_name was renamed to * \ref H5Oget_info_by_name1().</td> * </tr> * <tr> * <td></td> - * <td>The macro #H5Oget_info_by_name and the function \ref H5Oget_info_name2() + * <td>The macro #H5Oget_info_by_name and the function \ref H5Oget_info_by_name2() * were introduced in this release.</td> * </tr> * <tr> * <td>1.8.8</td> - * <td>Fortran 2003 subroutine and \ref h5o_info_t derived + * <td>Fortran 2003 subroutine and \ref H5O_info_t derived * type introduced in this release.</td> * </tr> * <tr> @@ -95,5 +95,5 @@ * </tr> * </table> * - * + * */ diff --git a/doxygen/dox/api-compat-macros.dox b/doxygen/dox/api-compat-macros.dox index c5c868b..6b85ccb 100644 --- a/doxygen/dox/api-compat-macros.dox +++ b/doxygen/dox/api-compat-macros.dox @@ -146,8 +146,8 @@ <table border="1" cellpadding="3"> <tr> <th>\Code{configure} flag</th> - <th>Macros map to release<br/>(versioned function; \Code{H5Lvisit} shown)</th> - <th>Deprecated functions available? <br/>(\Code{H5Lvisit1})</th> + <th>Macros map to release <br/> (versioned function; \Code{H5Lvisit} shown)</th> + <th>Deprecated functions available? <br/> (\Code{H5Lvisit1})</th> </tr> <tr align="center"> <td>\Code{--with-default-api-version=v112} <br/> (the default in 1.12)</td> @@ -304,7 +304,7 @@ \subsubsection fun-options-112 Function Mapping Options in Releases 1.12.x <table> <tr> - <th style="text-align: left;">Macro<br/>(\Code{H5xxx})</th> + <th style="text-align: left;">Macro <br/> (\Code{H5xxx})</th> <th>Default function used if no macro specified <ul><li>Function/struct mapping:\Code{H5xxx_vers=N}</li></ul> </th> @@ -507,7 +507,7 @@ <table> <tr> <th>Macro</th> - <th>Default function used<br/><sub>(if no macro specified)</sub></th> + <th>Default function used <br/> <sub>(if no macro specified)</sub></th> <th>Introduced in</th> <th>\Code{h5cc} version flag and value</th> <th>Mapped to function or struct</th> @@ -603,7 +603,7 @@ <tr> <th>Macro</th> <th><code>h5cc</code> version flag and value</th> - <th>Mapped to function<br/>or struct</th> + <th>Mapped to function <br/> or struct</th> </tr> <tr> <td rowspan="2">H5Acreate()</td> @@ -686,7 +686,7 @@ <td>H5Eget_auto2()</td> </tr> <tr> - <td rowspan="2">\ref H5E_auto_t <br/> Struct for H5Eset_auto() <br/> and H5Eget_auto()</td> + <td rowspan="2">\ref H5E_auto_t <br/> struct for H5Eset_auto() <br/> and H5Eget_auto()</td> <td>\Code{DH5E_auto_t_vers=1}</td> <td>\ref H5E_auto1_t</td> </tr> @@ -719,12 +719,12 @@ </tr> <tr> <td>\Code{DH5Gopen_vers=2}</td> - <td>H5Gopen2}</td> + <td>H5Gopen2()</td> </tr> <tr> <td rowspan="2">H5Pget_filter()</td> <td>\Code{DH5Pget_filter_vers=1}</td> - <td>H5Pget_filter1}()/td> + <td>H5Pget_filter1()</td> </tr> <tr> <td>\Code{DH5Pget_filter_vers=2}</td> @@ -751,7 +751,7 @@ <tr> <td rowspan="2">H5Pregister()</td> <td>\Code{DH5Pregister_vers=1}</td> - <td>H5Pregister1}</td> + <td>H5Pregister1()</td> </tr> <tr> <td>\Code{DH5Pregister_vers=2}</td> @@ -803,7 +803,7 @@ <td>H5Topen2()</td> </tr> <tr> - <td rowspan="2">\ref H5Z_class_t Struct for H5Zregister()</td> + <td rowspan="2">\ref H5Z_class_t struct for H5Zregister()</td> <td>\Code{DH5Z_class_t_vers=1}</td> <td>\ref H5Z_class1_t</td> </tr> @@ -811,10 +811,89 @@ <td>\Code{DH5Z_class_t_vers=2}</td> <td>\ref H5Z_class2_t</td> </tr> - </table></div> - + </table> + </div> \subsubsection further Further Information + It is possible to specify multiple function mappings for a single application build: + \code{.sh} + h5cc ... -DH5Rdereference_vers=1 -DH5Fget_info_vers=2 ... + \endcode + As a result of the function and struct mappings in this compile example, all + occurrences of the macro \Code{H5Rdereference} will be mapped to \Code{H5Rdereference1} + and all occurrences of the macro \Code{H5Fget_info} will be mapped to \Code{H5Fget_info2} + for the application being built. + + The function and struct mappings can be used to guarantee that a given API compatibility + macro will be mapped to the desired underlying function or struct version regardless of + the library or application mappings. In cases where an application may benefit greatly + from features offered by some of the later APIs, or must continue to use some earlier + API versions for compatibility reasons, this fine-grained control may be very important. + + As noted earlier, the function mappings can only reference versioned functions that are + included in the HDF5 library, as determined by the configure flag used to build the + library. For example, if the HDF5 library being linked with the application was built + with the \Code{--disable-deprecated-symbols} option, version 1 of the underlying functions + would not be available, and the example above that defined \Code{H5Rdereference_vers=1} + would not be supported. + + The function mappings do not negate any available functions. If \Code{H5Rdereference1} + is available in the installed version of the HDF5 library, and the application was not + compiled with the \Code{-DH5_NO_DEPRECATED_SYMBOLS} flag, the function \Code{H5Rdereference1} + will remain available to the application through its versioned name. Similarly, + \Code{H5Rdereference2} will remain available to the application as \Code{H5Rdereference2}. + The function mapping version flag \Code{H5Rdereference_vers} only controls the mapping of + the API compatibility macro \Code{H5Rdereference} to one of the two available functions. + + This can be especially useful in any case where the programmer does not have direct control + over global macro definitions, such as when writing code meant to be copied to multiple + applications or when writing code in a header file. + \section macros Compatibility Macros in HDF5 1.6.8 and Later + A series of similar compatibility macros were introduced into the release 1.6 + series of the library, starting with release 1.6.8. These macros simply alias the + '1' version functions, callbacks, and typedefs listed above to their original + non-numbered names. + + These macros were strictly a forward-looking feature at that time; they were not + necessary for compatibility in 1.6.x. These macros were created at that time to + enable writing code that could be used with any version of the library after 1.6.8 + and any library compilation options except \Code{H5_NO_DEPRECATED_SYMBOLS}, by always + using the '1' version of versioned functions and types. For example, \Code{H5Dopen1} + will always be interpreted in exactly the same manner by any version of the library + since 1.6.8. + \section use-case Common Use Case -*/
\ No newline at end of file + A common scenario where the API compatibility macros may be helpful is the migration + of an existing application to a new HDF5 release. An incremental migration plan is + outlined here: + <ol> + <li>Build the HDF5 library without specifying any library mapping \Code{configure} + flag. In this default mode, the 1.6.x, 1.8.x, and 1.10.x versions of the + underlying functions are available, and the API compatibility macros will + be mapped to the current HDF5 versioned functions.</li> + <li>Compile the application with the \Code{-DH5_USE_NN_API} application mapping + option if it was written for use with an earlier HDF5 library. Because the + application mapping overrides the library mapping, the macros will all be + mapped to the earlier versions of the functions.</li> + <li>Remap one API compatibility macro at a time (or sets of macros), to use the + current HDF5 versions. At each stage, use the function mappings to map the macros + being worked on to the current versions. For example, use the + \Code{-DH5Rdereference_vers=2} version flag setting to remap the \Code{H5Rdereference} + macro to \Code{H5Rdereference2}, the 1.10.x version. + + During this step, the application code will need to be modified to change the calling + parameters used with the API compatibility macros to match the number and type + of the 1.10.x versioned functions. The macro name, for example \Code{H5Rdereference}, + should continue to be used in the code, to allow for possible re-mappings to later + versioned functions in a future release.</li> + <li>After all macros have been migrated to the latest versioned functions in step 3, + compile the application without any application or function mappings. This build + uses the library mappings set in step 1, and maps API compatibility macros to the + latest versions.</li> + <li>Finally, compile the application with the application mapping + \Code{-DH5_NO_DEPRECATED_SYMBOLS}, and address any failures to complete + the application migration process.</li> + </ol> + + */
\ No newline at end of file diff --git a/doxygen/dox/mainpage.dox b/doxygen/dox/mainpage.dox index 7b62916..83fc323 100644 --- a/doxygen/dox/mainpage.dox +++ b/doxygen/dox/mainpage.dox @@ -33,4 +33,4 @@ * opportunity to close any temporary data structures that were set up when the * routine was called. The C++ application should save some state as the * routine is started so that any problem that occurs might be diagnosed. - */ + */
\ No newline at end of file |