From 9ab92949aca897f44f48772aad2c9e2df98ff01f Mon Sep 17 00:00:00 2001 From: Pierre Granger Date: Thu, 5 Nov 2026 22:22:39 +0100 Subject: [PATCH] Give the library its own version: spine::version(), summary() and spine-dump --version project(spine-reader VERSION X.Y.Z) stays the only place the number is written. It reaches the code as the private compile definition SPINE_READER_VERSION_STRING, returned by the new spine::version() (spine/version.hpp, included by reader.hpp). SchemaReport::summary() now names both programs on the line after the path, so a model older than the file reads as a normal lag: SPINE 1.4.1, format_version 1 (V1); read by spine-reader 0.1.0 (model from SPINE 1.4.0) instead of "SPINE 1.4.1, format_version 1 (V1), read with model 1.4.0". SchemaReport keeps its layout. This line is the only change the CAFMakers' logs show. spine-dump --version prints the same pair and exits 0, whatever other arguments are given. The tests no longer write the spine-reader or model version as literals: test_reader.cpp builds them from spine::version() and SPINE_READER_MODEL_SPINE_VERSION. check_spine_dump.cmake gets them from tests/CMakeLists.txt, which reads the model version from model.hpp and reconfigures when that header is regenerated. The file versions in those strings describe the frozen test files and stay literal. The README gains a Versions section, and the EGM.md contracts describe the new function, the summary line and --version. --- CMakeLists.txt | 2 ++ EGM.md | 10 ++++++++-- README.md | 15 +++++++++++++++ examples/EGM.md | 10 ++++++++-- examples/spine_dump.cpp | 15 +++++++++++++-- include/EGM.md | 8 ++++---- include/spine/EGM.md | 10 ++++++++-- include/spine/reader.hpp | 1 + include/spine/version.hpp | 12 ++++++++++++ src/EGM.md | 5 +++++ src/schema_report.cpp | 5 +++-- src/version.cpp | 11 +++++++++++ tests/CMakeLists.txt | 13 ++++++++++++- tests/check_spine_dump.cmake | 26 +++++++++++++++++++++++--- tests/test_reader.cpp | 10 ++++++---- 15 files changed, 131 insertions(+), 22 deletions(-) create mode 100644 include/spine/version.hpp create mode 100644 src/version.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 14146f7..bd482b0 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -44,6 +44,8 @@ target_include_directories(spine_reader PRIVATE ${PROJECT_SOURCE_DIR}/src) target_link_libraries(spine_reader PRIVATE HDF5::HDF5) +# spine::version() (src/version.cpp): project(VERSION) above is the only place it is written. +target_compile_definitions(spine_reader PRIVATE SPINE_READER_VERSION_STRING="${PROJECT_VERSION}") if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang") target_compile_options(spine_reader PRIVATE -Wall -Wextra -Wpedantic) endif() diff --git a/EGM.md b/EGM.md index 8dc7228..6a4918b 100644 --- a/EGM.md +++ b/EGM.md @@ -41,19 +41,25 @@ Build and packaging (`CMakeLists.txt`): - It also exports the CMake package `SpineReader` (`SpineReaderTargets`, version compatibility `SameMinorVersion`). Consumers load it with `find_package(SpineReader)` and `-DCMAKE_PREFIX_PATH=`. +- Version: `project(spine-reader VERSION X.Y.Z)` is the only place the library's version is + written. It reaches the code as the private compile definition `SPINE_READER_VERSION_STRING`, + returned by `spine::version()` and printed by `SchemaReport::summary()` and + `spine-dump --version`. A release is the git tag `vX.Y.Z` made from it + (`ci/check_tag_version.sh`). ## Subdirectories & System Boundaries - include: [./include/EGM.md](./include/EGM.md) - Public header root (installed as `include/spine`). - [./include/spine/EGM.md](./include/spine/EGM.md) - `Reader`, `ReaderOptions`, `Event`, - `Match`, `SchemaReport`/`ProductReport`, descriptors, `Object`, `spine::Error`. + `Match`, `SchemaReport`/`ProductReport`, descriptors, `Object`, `spine::Error`, + `spine::version()`. - [./include/spine/model/EGM.md](./include/spine/model/EGM.md) - Generated SPINE 1.4.0 classes (`RecoParticle`, `TruthParticle`, `RecoInteraction`, `TruthInteraction`, `RunInfo`, `Trigger`, `ImageMeta3D`, `Flash`, `CRTHit`, `FlashHypothesis`) and enums. Do not edit. - [./include/spine/detail/EGM.md](./include/spine/detail/EGM.md) - `ColumnBuffer` and `assign<&Class::member>`, the bridge from read columns to model members. - src: [./src/EGM.md](./src/EGM.md) - Implementation of `Reader` and `Event`, descriptor - helpers, `SchemaReport::summary`. + helpers, `SchemaReport::summary`, `spine::version()`. - [./src/h5/EGM.md](./src/h5/EGM.md) - Move-only HDF5 handles, `ErrorSilencer`, `check`/`fail`, read-only open and attribute helpers. - [./src/core/EGM.md](./src/core/EGM.md) - `FileSource`/`ProductSource`, V1 and V2 product diff --git a/README.md b/README.md index b8b58b6..de0c9c0 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,21 @@ needs only the HDF5 C library, version 1.12 or newer. Status: under construction. +## Versions + +- A spine-reader release is a git tag `vX.Y.Z` made from `project(spine-reader VERSION X.Y.Z)` + in `CMakeLists.txt`, which is the only place the number is written. Before pushing a tag, run + `ci/check_tag_version.sh vX.Y.Z`; CI runs it again on the tag push. +- `spine::version()` (`spine/version.hpp`) and `spine-dump --version` print it. Each file's + `SchemaReport::summary()` prints it too, next to the SPINE version that wrote the file and the + SPINE version the model was generated from, for example + `SPINE 1.4.1, format_version 1 (V1); read by spine-reader 0.1.0 (model from SPINE 1.4.0)`. +- `find_package(SpineReader X.Y)` accepts any X.Y.z (`SameMinorVersion`). +- Between releases, builds of `main` report the last release number; production builds should + use a tag. +- A published tag is never moved or deleted. A wrong release is followed by a fixed one, and is + listed here as withdrawn. No release has been withdrawn. + ## Layout | Path | Contents | diff --git a/examples/EGM.md b/examples/EGM.md index d28078d..c4a0bb0 100644 --- a/examples/EGM.md +++ b/examples/EGM.md @@ -14,7 +14,10 @@ repository. It is a debugging aid, and its output is pinned by the is built and installed to `${CMAKE_INSTALL_BINDIR}` only when the option `SPINE_READER_BUILD_TOOLS` is on. The option defaults to on when this is the top-level project. -- Command line: `spine-dump [--events N] file.h5 [more.h5 ...]`. +- Command line: `spine-dump [--events N] file.h5 [more.h5 ...]`, or `spine-dump --version`. + - `--version` prints `spine-dump: spine-reader (model from SPINE + )` and exits `0`, whatever other arguments are given; + no file is opened. - `--events N` sets the number of events to print (default `5`). `N` is parsed with `std::strtoull`. A `--events` with nothing after it is treated as a file path. @@ -43,7 +46,10 @@ repository. It is a debugging aid, and its output is pinned by the - The exact output format is tested. `tests/check_spine_dump.cmake` matches substrings such as `"6 events\nevent 0 (run 7, subrun 2, event 101): ..."`, checks the `--events` limit (`--events 1`, `3`, `99`; the default of 5 is not - tested), and checks exit codes `2` and `1`. + tested), checks `--version`, and checks exit codes `2` and `1`. It gets the + expected spine-reader and model versions from `tests/CMakeLists.txt` + (`-DREADER_VERSION`, `-DMODEL_VERSION`); the file versions it expects + (`SPINE 1.4.0`) describe the frozen test files. Any change to the printed text, the line order or the exit codes must be made in that script too. - Only `spine::Error` is caught. Any other exception ends the program diff --git a/examples/spine_dump.cpp b/examples/spine_dump.cpp index a0df91b..3efe389 100644 --- a/examples/spine_dump.cpp +++ b/examples/spine_dump.cpp @@ -1,9 +1,11 @@ // spine-dump: print what spine-reader sees in SPINE HDF5 files. // // spine-dump [--events N] file.h5 [more.h5 ...] +// spine-dump --version // // Prints each file's schema report, then per-event object counts and the first reco -// particle of each event. +// particle of each event. --version prints the spine-reader release and the SPINE release the +// model was generated from, and exits 0, whatever other arguments are given. #include #include @@ -14,6 +16,14 @@ #include int main(int argc, char** argv) { + for (int i = 1; i < argc; ++i) { + if (std::string(argv[i]) == "--version") { + std::cout << "spine-dump: spine-reader " << spine::version() << " (model from SPINE " + << SPINE_READER_MODEL_SPINE_VERSION << ")\n"; + return 0; + } + } + std::vector paths; std::uint64_t max_events = 5; for (int i = 1; i < argc; ++i) { @@ -25,7 +35,8 @@ int main(int argc, char** argv) { } } if (paths.empty()) { - std::cerr << "usage: spine-dump [--events N] file.h5 [more.h5 ...]\n"; + std::cerr << "usage: spine-dump [--events N] file.h5 [more.h5 ...]\n" + " spine-dump --version\n"; return 2; } diff --git a/include/EGM.md b/include/EGM.md index a93e586..7417d79 100644 --- a/include/EGM.md +++ b/include/EGM.md @@ -12,9 +12,9 @@ Everything lives under the `spine` namespace directory. ## Subdirectories & Boundaries - spine: [./spine/EGM.md](./spine/EGM.md): the public API. `Reader`, `ReaderOptions`, `Event`, - `Match`, `SchemaReport`, `Error`, the reflection descriptors, and the `Object` base. It - contains: - - [./spine/model/EGM.md](./spine/model/EGM.md): SPINE 1.4.0 classes and enums generated by - `tools/gen/generate.py` (do not hand-edit). + `Match`, `SchemaReport`, `Error`, `version()`, the reflection descriptors, and the `Object` + base. It contains: + - [./spine/model/EGM.md](./spine/model/EGM.md): the SPINE classes and enums generated by + `tools/gen/generate.py` from the committed schema (do not hand-edit). - [./spine/detail/EGM.md](./spine/detail/EGM.md): internal `ColumnBuffer` and `assign<&Class::member>` row-copy templates. diff --git a/include/spine/EGM.md b/include/spine/EGM.md index 355c14a..0eabf8c 100644 --- a/include/spine/EGM.md +++ b/include/spine/EGM.md @@ -30,7 +30,12 @@ reflection tables they use come from `descriptor.hpp`. All of these headers are `enum_notes`, and `complete()`. - `struct SchemaReport`: `path`, `spine_version`, `format_version`, `layout` (`"V1"`, `"V2Root"` or `"V2Products"`), `model_version`, `products`, `skipped`, and - `summary()`. + `summary()`. The line after the path reads `SPINE , + format_version (); read by spine-reader (model from SPINE + )`. +- `version.hpp`: `const char* version() noexcept`, the release number of the linked library + (`project(VERSION)`, `"X.Y.Z"`). Between releases, builds of main report the last release. + `reader.hpp` includes it. - `descriptor.hpp` - `enum class ScalarType`, `constexpr scalar_size(ScalarType)`, and `to_string(ScalarType)` - `struct EnumMember` and `struct EnumDescriptor` (with `name_of(value)`) @@ -45,7 +50,8 @@ reflection tables they use come from `descriptor.hpp`. All of these headers are is used by the binder. - `error.hpp`: `class Error : public std::runtime_error`. - `model.hpp` (generated by `tools/gen/generate.py`, do not edit): umbrella include of every - model header, `SPINE_READER_MODEL_SPINE_VERSION` (`"1.4.0"`), and the X-macro + model header, `SPINE_READER_MODEL_SPINE_VERSION` (the SPINE release of the committed + schema, not the library's version), and the X-macro `SPINE_READER_FOR_EACH_CLASS(X)`. - Subdirectories: - [model](./model/EGM.md): generated SPINE classes and enums diff --git a/include/spine/reader.hpp b/include/spine/reader.hpp index a52bb3b..e0b97a8 100644 --- a/include/spine/reader.hpp +++ b/include/spine/reader.hpp @@ -9,6 +9,7 @@ #include #include +#include namespace spine { diff --git a/include/spine/version.hpp b/include/spine/version.hpp new file mode 100644 index 0000000..c36514c --- /dev/null +++ b/include/spine/version.hpp @@ -0,0 +1,12 @@ +#pragma once + +namespace spine { + +/// Release number of the linked spine-reader library, "X.Y.Z": `project(VERSION)` in the +/// top-level CMakeLists.txt, which is the only place it is written. A release is the git tag +/// "vX.Y.Z" made from it; between releases, builds of main report the last release number. +/// The SPINE release the C++ model was generated from is `SPINE_READER_MODEL_SPINE_VERSION` +/// (spine/model.hpp), a different number. +const char* version() noexcept; + +} // namespace spine diff --git a/src/EGM.md b/src/EGM.md index b3a759d..c12b1c9 100644 --- a/src/EGM.md +++ b/src/EGM.md @@ -37,6 +37,11 @@ Direct sources: - `descriptor.cpp` defines `spine::to_string(ScalarType)`, `EnumDescriptor::name_of(value)` and `ClassDescriptor::find(field_name)` (`include/spine/descriptor.hpp`). - `schema_report.cpp` defines `spine::SchemaReport::summary()` (`include/spine/schema_report.hpp`). + Its line after the path names the file's SPINE version, the spine-reader version + (`spine::version()`) and the model's SPINE version. +- `version.cpp` defines `spine::version()` (`include/spine/version.hpp`). It returns + `SPINE_READER_VERSION_STRING`, a compile definition that `CMakeLists.txt` sets to + `${PROJECT_VERSION}`; the file refuses to compile without it. Subdirectory contracts: diff --git a/src/schema_report.cpp b/src/schema_report.cpp index f94fb9c..330ec8b 100644 --- a/src/schema_report.cpp +++ b/src/schema_report.cpp @@ -1,4 +1,5 @@ #include +#include #include @@ -17,8 +18,8 @@ void list(std::ostringstream& out, const char* label, const std::vector + +#ifndef SPINE_READER_VERSION_STRING +#error "SPINE_READER_VERSION_STRING must be defined by the build (CMakeLists.txt)" +#endif + +namespace spine { + +const char* version() noexcept { return SPINE_READER_VERSION_STRING; } + +} // namespace spine diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 169dee2..0d6ca15 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -53,10 +53,21 @@ else() message(WARNING "No Python 3 interpreter: the generated-model checks are not registered") endif() -# spine-dump on the Reader test files: what it prints, and its exit codes. +# spine-dump on the Reader test files: what it prints, and its exit codes. The script compares +# the versions it prints with the library's (project(VERSION)) and with the model's SPINE +# release, read here from the generated model header; a regenerated header reconfigures. if(TARGET spine-dump) + set(model_header ${PROJECT_SOURCE_DIR}/include/spine/model.hpp) + set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${model_header}) + file(STRINGS ${model_header} model_version_line + REGEX "^#define SPINE_READER_MODEL_SPINE_VERSION ") + string(REGEX REPLACE ".*\"([^\"]*)\".*" "\\1" model_version "${model_version_line}") + if(NOT model_version MATCHES "^[0-9]+\\.[0-9]+\\.[0-9]+$") + message(FATAL_ERROR "no SPINE_READER_MODEL_SPINE_VERSION in ${model_header}") + endif() add_test(NAME spine_dump_output COMMAND ${CMAKE_COMMAND} -DSPINE_DUMP=$ -DDATA=${CMAKE_CURRENT_SOURCE_DIR}/data + -DREADER_VERSION=${PROJECT_VERSION} -DMODEL_VERSION=${model_version} -P ${CMAKE_CURRENT_SOURCE_DIR}/check_spine_dump.cmake) endif() diff --git a/tests/check_spine_dump.cmake b/tests/check_spine_dump.cmake index 07efc68..c60a316 100644 --- a/tests/check_spine_dump.cmake +++ b/tests/check_spine_dump.cmake @@ -1,5 +1,13 @@ # Runs spine-dump on the Reader test files and checks what it prints and returns. -# cmake -DSPINE_DUMP= -DDATA= -P check_spine_dump.cmake +# cmake -DSPINE_DUMP= -DDATA= -DREADER_VERSION= -DMODEL_VERSION= +# -P check_spine_dump.cmake +# READER_VERSION is project(VERSION); MODEL_VERSION is SPINE_READER_MODEL_SPINE_VERSION. + +foreach(var SPINE_DUMP DATA READER_VERSION MODEL_VERSION) + if(NOT DEFINED ${var} OR "${${var}}" STREQUAL "") + message(FATAL_ERROR "check_spine_dump.cmake: pass -D${var}=...") + endif() +endforeach() function(run_dump output_var code_var) execute_process(COMMAND ${SPINE_DUMP} ${ARGN} @@ -31,8 +39,11 @@ run_dump(text code --events 3 ${A} ${B} ${C}) if(NOT code EQUAL 0) message(FATAL_ERROR "spine-dump failed with ${code}:\n${text}") endif() -expect_in("${text}" "${A}\n SPINE 1.4.0, format_version 1 (V1), read with model 1.4.0") -expect_in("${text}" "${B}\n SPINE 1.4.0, format_version 2 (V2Products), read with model 1.4.0") +# "SPINE 1.4.0" is the writer of these frozen test files; the other two versions come from +# the build. +set(read_by "; read by spine-reader ${READER_VERSION} (model from SPINE ${MODEL_VERSION})") +expect_in("${text}" "${A}\n SPINE 1.4.0, format_version 1 (V1)${read_by}") +expect_in("${text}" "${B}\n SPINE 1.4.0, format_version 2 (V2Products)${read_by}") expect_in("${text}" "meta [Meta]: all model fields read") expect_in("${text}" "index: array product") string(CONCAT first_event @@ -59,6 +70,15 @@ string(CONCAT b_second_event "0 truth interactions, 2 truth particles") expect_in("${text}" "${b_second_event}") +# --version prints both versions and exits 0, even with a file on the command line, which it +# does not read +run_dump(text code --version ${A}) +if(NOT code EQUAL 0) + message(FATAL_ERROR "spine-dump --version returned ${code}, expected 0:\n${text}") +endif() +expect_in("${text}" "spine-dump: spine-reader ${READER_VERSION} (model from SPINE ${MODEL_VERSION})") +expect_not_in("${text}" "events") + # usage: no files is exit code 2 run_dump(text code) if(NOT code EQUAL 2) diff --git a/tests/test_reader.cpp b/tests/test_reader.cpp index 5974e60..5126b84 100644 --- a/tests/test_reader.cpp +++ b/tests/test_reader.cpp @@ -555,10 +555,12 @@ TEST_CASE("non-object products and products of unknown classes are listed as not report.skipped.end()); CHECK(report.skipped.size() == 1); - // the summary says so, after the products + // the summary says so, after the products. The file versions ("SPINE 1.4.0") describe these + // frozen test files; the spine-reader and model versions come from the build. + const std::string read_by = std::string("; read by spine-reader ") + spine::version() + + " (model from SPINE " + SPINE_READER_MODEL_SPINE_VERSION + ")\n"; const std::string summary = report.summary(); - CHECK(contains(summary, three_files()[0] + - "\n SPINE 1.4.0, format_version 1 (V1), read with model 1.4.0\n")); + CHECK(contains(summary, three_files()[0] + "\n SPINE 1.4.0, format_version 1 (V1)" + read_by)); CHECK(contains(summary, "\n reco_particles [RecoParticle]: all model fields read\n")); const std::string tail = " not read:\n index: array product\n"; REQUIRE(summary.size() > tail.size()); @@ -567,7 +569,7 @@ TEST_CASE("non-object products and products of unknown classes are listed as not // a file that does not say which SPINE wrote it Reader unversioned(core_file("edge_v2_noversion.h5")); CHECK(contains(unversioned.schema_report().summary(), - "\n SPINE unknown, format_version 1 (V2Products), read with model 1.4.0\n")); + "\n SPINE unknown, format_version 1 (V2Products)" + read_by)); // edge_v1_columns.h5 has an 'Edge' class no model knows Reader edge(core_file("edge_v1_columns.h5"));