summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorjhendersonHDF <jhenderson@hdfgroup.org>2023-11-15 14:20:50 (GMT)
committerGitHub <noreply@github.com>2023-11-15 14:20:50 (GMT)
commitc779464bfe3dabd767144526a868a5b06538161f (patch)
tree24dbf660c97b36d8634ce2cd8440cb2b61e3bcb3 /doc
parente807dee0fd6c007d7c41327c1ed0e8f5bc617f72 (diff)
downloadhdf5-c779464bfe3dabd767144526a868a5b06538161f.zip
hdf5-c779464bfe3dabd767144526a868a5b06538161f.tar.gz
hdf5-c779464bfe3dabd767144526a868a5b06538161f.tar.bz2
Add GitHub actions for testing VOL connectors (#3849)
* Fix issue with HDF5_VOL_ALLOW_EXTERNAL CMake variable * Add initial API test workflow * Initialize parallel testing with MPI_THREAD_MULTIPLE when testing API * Add CMake variable to allow specifying a VOL connector's package name * Remove call to MPI_Init in serial API tests While previously necessary, it now interferes with VOL connectors that may need to be initialized with MPI_THREAD_MULTIPLE
Diffstat (limited to 'doc')
-rw-r--r--doc/cmake-vols-fetchcontent.md26
1 files changed, 19 insertions, 7 deletions
diff --git a/doc/cmake-vols-fetchcontent.md b/doc/cmake-vols-fetchcontent.md
index 9d3c1ba..ff05913 100644
--- a/doc/cmake-vols-fetchcontent.md
+++ b/doc/cmake-vols-fetchcontent.md
@@ -97,12 +97,21 @@ After the VOL's internal name is generated, the following new variables get crea
variable must be set in order for the VOL connector to be testable with
HDF5's tests.
+ HDF5_VOL_<VOL name>_CMAKE_PACKAGE_NAME (Default: "<lowercased <VOL name>>")
+ This variable specifies the exact name that would be passed to CMake
+ find_package(...) calls for the VOL connector in question. It is used as
+ the dependency name when making CMake FetchContent calls to try to ensure
+ that any other VOL connectors to be built which depend on this VOL connector
+ can make find_package(...) calls for this VOL connector at configure time.
+ By default, this variable is set to a lowercased version of the internal
+ name generated for the VOL connector (described above).
+
HDF5_VOL_<VOL name>_TEST_PARALLEL (Default: OFF)
This variable determines whether the VOL connector with the CMake-internal
name '<VOL name>' should be tested against HDF5's parallel tests.
If the source was retrieved from a Git URL, then the following variable will additionally be created:
-
+
HDF5_VOL_<VOL name>_BRANCH (Default: "main")
This variable specifies the git branch name or tag to use when fetching
the source code for the VOL connector with the CMake-internal name
@@ -111,9 +120,10 @@ If the source was retrieved from a Git URL, then the following variable will add
As an example, this would create the following variables for the
previously-mentioned VOL connector if it is retrieved from a URL:
- HDF5_VOL_VOL-ASYNC_BRANCH
- HDF5_VOL_VOL-ASYNC_NAME
- HDF5_VOL_VOL-ASYNC_TEST_PARALLEL
+ HDF5_VOL_VOL-ASYNC_NAME ""
+ HDF5_VOL_VOL-ASYNC_CMAKE_PACKAGE_NAME "vol-async"
+ HDF5_VOL_VOL-ASYNC_BRANCH "main"
+ HDF5_VOL_VOL-ASYNC_TEST_PARALLEL OFF
**NOTE**
If a VOL connector requires extra information to be passed in its
@@ -139,9 +149,10 @@ would typically be passed when building HDF5, such as `CMAKE_INSTALL_PREFIX`,
-DHDF5_TEST_API=ON
-DHDF5_VOL_ALLOW_EXTERNAL="GIT"
-DHDF5_VOL_URL01=https://github.com/hpc-io/vol-async.git
- -DHDF5_VOL_VOL-ASYNC_BRANCH=develop
+ -DHDF5_VOL_VOL-ASYNC_BRANCH=develop
-DHDF5_VOL_VOL-ASYNC_NAME="async under_vol=0\;under_info={}"
- -DHDF5_VOL_VOL-ASYNC_TEST_PARALLEL=ON ..
+ -DHDF5_VOL_VOL-ASYNC_TEST_PARALLEL=ON
+ ..
Here, we are specifying that:
@@ -156,7 +167,8 @@ Here, we are specifying that:
variable should be set to "async under_vol=0\;under_info={}", which
specifies that the VOL connector with the canonical name "async" should
be loaded and it should be passed the string "under_vol=0;under_info={}"
- for its configuration
+ for its configuration (note the backslash-escaping of semicolons in the string
+ provided)
* The Asynchronous I/O VOL connector should be tested against HDF5's parallel API tests
Note that this also assumes that the Asynchronous I/O VOL connector's