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"));