Skip to content

Commit 6ecfbe3

Browse files
steven-vargasteven-varga
committed
[#278]:svarga:docs, add scripts/README.md documenting cdash and amalgamate.py
1 parent 733d64d commit 6ecfbe3

1 file changed

Lines changed: 121 additions & 0 deletions

File tree

‎scripts/README.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# `scripts/`
2+
3+
Developer tooling for h5cpp. Each script is self-contained and documented in
4+
its own header; this file is the quick reference.
5+
6+
---
7+
8+
## `cdash` — off-CI CDash test + coverage submission
9+
10+
Builds h5cpp, runs the test suite, collects coverage, and uploads the results
11+
to [my.cdash.org](https://my.cdash.org/index.php?project=h5cpp) from any
12+
machine — desktop, laptop, or an HPC cluster under SLURM. It is a thin wrapper
13+
over `ctest -S CTestDashboard.cmake` (the CTest dashboard script that does the
14+
actual configure → build → test → coverage → submit pipeline).
15+
16+
### Quick start
17+
18+
```bash
19+
git submodule update --init --recursive # vendored thirdparty libs must be present
20+
CXX=g++-14 GCOV=gcov-14 scripts/cdash # coverage + examples, then submit
21+
```
22+
23+
The result appears on CDash under the **Experimental** group, tagged with the
24+
host's site name and an auto build name like `Linux-x86_64-g++-14-Debug`.
25+
26+
### Defaults
27+
28+
| Option | Default | Notes |
29+
|--------|---------|-------|
30+
| `COVERAGE` | `ON` | forces a `Debug -O0 -g --coverage` build + gcov collection |
31+
| `BUILD_EXAMPLES` | `ON` | also builds the `examples/` tree |
32+
| `SUBMIT` | `ON` | upload to CDash; set `OFF` for a local dry run |
33+
| `TRACK` | `Experimental` | CDash group — `Nightly` for scheduled cron runs |
34+
| `BUILD_TYPE` | `Debug` (when `COVERAGE=ON`) | otherwise `Release` |
35+
| `JOBS` | SLURM allocation, else logical cores | see SLURM section |
36+
37+
> **Track vs build type.** `Experimental`/`Nightly`/`Continuous` is the CDash
38+
> *group* (when/why a build ran). It is **not** an alternative to
39+
> `Release`/`Debug`, which is the *build type* (how it was compiled). Coverage
40+
> requires `Debug` instrumentation, so coverage runs are always `Debug`.
41+
42+
### Common invocations
43+
44+
```bash
45+
scripts/cdash # coverage + examples, submit (defaults)
46+
scripts/cdash SUBMIT=OFF # dry run: build + test + coverage, no upload
47+
scripts/cdash COVERAGE=OFF BUILD_TYPE=Release # plain Release build, no coverage
48+
scripts/cdash HDF5_DIR=/opt/hdf5/cmake # pin HDF5 (module installs / discovery trap)
49+
CXX=g++-14 GCOV=gcov-14 scripts/cdash # match gcov to the compiler
50+
CXX=clang++-18 GCOV='llvm-cov gcov' scripts/cdash
51+
```
52+
53+
All `KEY=value` arguments are forwarded to `CTestDashboard.cmake` as `-DKEY=value`.
54+
Full option list: `HDF5_ROOT`, `HDF5_DIR`, `CTEST_SITE`, `CTEST_BUILD_NAME`,
55+
`JOBS`, `TRACK`, `SUBMIT`, `COVERAGE`, `BUILD_EXAMPLES`, `BUILD_TYPE`.
56+
57+
### Prerequisites
58+
59+
- `cmake` ≥ 3.17, `ctest`, and `ninja` (preferred) or `make`
60+
- A compiler with `--coverage` support **and a matching `gcov`** — e.g. `g++-14`
61+
needs `gcov-14`, not the default `gcov`. Set both via `CXX=` and `GCOV=`.
62+
(`lcov` is **not** needed — CTest drives `gcov` directly.)
63+
- HDF5 ≥ 1.12.3 — auto-detected, or pinned with `HDF5_DIR=.../cmake`
64+
- thirdparty submodules initialised (the build won't configure without them)
65+
- outbound HTTPS to `my.cdash.org` (open submission, no credentials)
66+
67+
### Running under SLURM
68+
69+
No special flags are required — the script adapts to the job automatically:
70+
71+
- **`JOBS`** is derived from `SLURM_CPUS_PER_TASK` → `SLURM_CPUS_ON_NODE` →
72+
logical core count, so the build never oversubscribes a shared node.
73+
- **Site** defaults to `SLURM_CLUSTER_NAME` (so every node groups under one
74+
cluster on the dashboard); override with `CTEST_SITE`.
75+
- **Build name** is suffixed with the compute-node hostname so concurrent
76+
per-node submissions stay distinct.
77+
78+
```bash
79+
#!/bin/bash
80+
#SBATCH -N1 -c16 -t00:30:00
81+
module load hdf5 gcc # site-specific
82+
srun scripts/cdash HDF5_DIR="$HDF5_DIR/cmake"
83+
```
84+
85+
> **Compute-node networking.** Many HPC sites block direct outbound HTTPS from
86+
> compute nodes, so `SUBMIT=ON` may fail at the upload step. Options: run on a
87+
> login/interactive node, export `HTTPS_PROXY`, or use `SUBMIT=OFF` on the
88+
> compute node and re-run the submit from a login node.
89+
90+
### Troubleshooting
91+
92+
| Symptom | Cause / fix |
93+
|---------|-------------|
94+
| `gcov` version-mismatch / zeroed counts | `gcov` doesn't match the compiler → set `GCOV=gcov-NN` for `g++-NN` |
95+
| HDF5 not found / wrong version | pass `HDF5_DIR=.../cmake` (an `h5cc` on `PATH` can shadow the intended install) |
96+
| upload fails on a cluster | compute node has no outbound HTTPS — see the SLURM note above |
97+
| stale build | safe to `rm -rf build-cdash` between runs |
98+
99+
---
100+
101+
## `amalgamate.py` — single-header generator
102+
103+
Concatenates the modular h5cpp headers into one self-contained `h5cpp.hpp`,
104+
stripping `#pragma once` and internal `#include "H5*.hpp"` / `compat.hpp`
105+
directives so the result compiles as a single translation unit. Useful for
106+
drop-in distribution or quick experimentation without the full include tree.
107+
108+
### Usage
109+
110+
```bash
111+
python3 scripts/amalgamate.py <input-dir> <output-file>
112+
113+
# example: amalgamate the in-tree headers into a build artifact
114+
python3 scripts/amalgamate.py h5cpp build/h5cpp.hpp
115+
```
116+
117+
- `<input-dir>` — the `h5cpp/` header directory (must contain the `core` and
118+
`io` umbrella files; their pre-`#ifndef` preambles are preserved).
119+
- `<output-file>` — destination path for the generated single header.
120+
121+
Requires Python 3; no third-party packages.

0 commit comments

Comments
 (0)