Matt L
767ac04b21
* Build the examples as C++11 to match the HDF5 C++ library The standalone examples build forces CMAKE_CXX_STANDARD 98, but H5public.h includes <cinttypes>, which requires C++11. Any C++ translation unit that includes hdf5.h is therefore affected, not just users of the C++ API, and the HDF5 C++ library itself is built as C++11 (config/flags/HDFCompilerCXXFlags.cmake). The C++ examples do not compile as a result, against static or shared HDF5 alike. Only the standalone build is affected, which is why this is not visible in ordinary use. The C++98 setting lives in BASIC_SETTINGS, and HDF5Examples/CMakeLists.txt skips that whole block when EXAMPLES_EXTERNALLY_CONFIGURED is set -- which HDF5 does for its own in-tree example build (config/cmake/HDF5ExampleCache.cmake). Built in tree, the examples inherit HDF5's C++11 and compile normally, and that is the path the CI workflows exercise. The standalone path, where the C++98 setting does apply, is driven by the release scripts rather than by the workflows, and has the C++ examples off by default. * Select the examples' HL, Fortran and C++ libraries on the right variable When the examples are built standalone against an installed HDF5, the HL, Fortran and C++ branches choose between the shared and static libraries using BUILD_SHARED_LIBS, while the C branch just above them uses H5EXAMPLE_USE_SHARED_LIBS. H5EXAMPLE_USE_SHARED_LIBS is what decides whether the "shared" or the "static" component is requested from find_package, so only the matching HDF5_<linkage>_<lang>_FOUND variables are ever set. BUILD_SHARED_LIBS cannot select a linkage on its own; it can only agree or fail to match. Of its four combinations with H5EXAMPLE_USE_SHARED_LIBS, three produce no observable difference. In the fourth, H5EXAMPLE_USE_SHARED_LIBS=ON with BUILD_SHARED_LIBS unset, the shared branch is not taken and the static branch cannot be, so the HL, Fortran and C++ examples are disabled with "libs not found" even though the libraries are installed and were found. Use H5EXAMPLE_USE_SHARED_LIBS, which is the declared option and is already what the C branch uses. A build driven through config/examples/CTestScript.cmake does not reach the broken combination, because it configures with HDF5Examples/config/cmake/cacheinit.cmake, which forces BUILD_SHARED_LIBS=ON. A direct cmake invocation without that cache file does. In either case the HL, Fortran and C++ examples are off by default, so this is only visible once they are enabled. BUILD_SHARED_LIBS remains documented as a user option in config/examples/HDF5_Examples_options.cmake but no longer influences library selection; that comment should be revisited separately.
The release_docs directory
This directory contains release artifacts only: changelogs, version history, release process documentation, and maintainer information.
User-facing guides (installation, build instructions, platform-specific docs)
have been moved to the docs/ directory.
Contents
CHANGELOG.md (formerly RELEASE.txt)
This is the changelog for the current version of the library.
For a MAJOR release (or in develop) this file lists all the changes since the
last major version. For a MINOR release (or in a maintenance branch), this file
lists all the changes since the last release in the maintenance branch.
Examples:
- The file for HDF5 1.14.0 includes all the changes since HDF5 1.12.0
- The file for HDF5 1.10.9 includes all the changes since HDF5 1.10.8
- The file in
developincludes all the changes since the last major release - The file in
hdf5_1_14includes all the changes since the last minor HDF5 1.14 release
HISTORY files
The HISTORY files contain the history of this branch of HDF5. They fall into
three categories.
HISTORY-[VERSION 1]-[VERSION 2].txt
These files are created when we release a new major version and include all
the changes that were made to the develop branch while creating a major release.
HISTORY-[VERSION].txt
This file contains the changes that were made to a maintenance branch since
it split off from develop. It will also be found in the develop branch
when experimental releases have been created.
Note that we make no effort to bring maintenance branch HISTORY files back to
develop. If you want to compare, say, 1.10.4 with 1.12.3, you'd have to get
the history files from those releases and compare them by hand.
RELEASE_PROCESS.md
Documentation for how releases are created and managed.
MAINTAINERS.md
Maintainer information for the project.
Creating new releases
MAJOR release
-
If there were experimental releases, merge the experimental
HISTORYfile and the currentCHANGELOG.mdby category to create a separate, unified file that ignores the experimental releases. Don't check this in yet or clobber any existingHISTORY/RELEASEfiles, but put it someplace handy for use in later steps. -
Create the new maintenance branch
In develop:
- Create the new
HISTORY-\[VERSION 1\]-\[VERSION 2\].txtfile- If there is an experimental
HISTORYfile, addCHANGELOG.mdto the beginning of it and use that - Otherwise, start with
CHANGELOG.md - Add the introduction boilerplate like in the other
HISTORYfiles (TOC, etc.)
- If there is an experimental
- Delete any experimental
HISTORYfile - Clear out
CHANGELOG.md
Note that we're KEEPING any experimental release history information in the
HISTORY-\[VERSION 1\]-\[VERSION 2\].txt file, so do NOT use the merged file in
the above steps!
In the new maintenance branch:
-
Create the new
HISTORY-\[VERSION\].txtfile- If there is an experimental
HISTORYfile use the combined file you created earlier - Otherwise, start with
CHANGELOG.md - Add the introduction boilerplate like in the other
HISTORYfiles (TOC, etc.)
- If there is an experimental
-
Delete any experimental
HISTORYfile -
Clear out
CHANGELOG.md -
Create the new release branch
In the new release branch:
- If there were experimental releases, use the combined file you created earlier as
CHANGELOG.md - Otherwise the
CHANGELOG.mdwill be used as-is
MINOR release
- Create the release branch
In the maintenance branch:
- Add the contents of
CHANGELOG.mdto the beginnnig ofHISTORY-\[VERSION\].txt - Clear out
CHANGELOG.md
EXPERIMENTAL release
- Add the contents of
CHANGELOG.mdto the beginnnig ofHISTORY-\[VERSION\].txt - Clear out
CHANGELOG.md