Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
10 changes: 8 additions & 2 deletions EGM.md
Original file line number Diff line number Diff line change
Expand Up @@ -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=<prefix>`.
- 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<T>`, `SchemaReport`/`ProductReport`, descriptors, `Object<N>`, `spine::Error`.
`Match<T>`, `SchemaReport`/`ProductReport`, descriptors, `Object<N>`, `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
Expand Down
15 changes: 15 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
10 changes: 8 additions & 2 deletions examples/EGM.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <spine::version()> (model from SPINE
<SPINE_READER_MODEL_SPINE_VERSION>)` 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.
Expand Down Expand Up @@ -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
Expand Down
15 changes: 13 additions & 2 deletions examples/spine_dump.cpp
Original file line number Diff line number Diff line change
@@ -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 <cstdlib>
#include <iostream>
Expand All @@ -14,6 +16,14 @@
#include <spine/reader.hpp>

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<std::string> paths;
std::uint64_t max_events = 5;
for (int i = 1; i < argc; ++i) {
Expand All @@ -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;
}

Expand Down
8 changes: 4 additions & 4 deletions include/EGM.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<N>` 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<N>`
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.
10 changes: 8 additions & 2 deletions include/spine/EGM.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <file version or "unknown">,
format_version <n> (<layout>); read by spine-reader <version()> (model from SPINE
<model_version>)`.
- `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)`)
Expand All @@ -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
Expand Down
1 change: 1 addition & 0 deletions include/spine/reader.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@

#include <spine/event.hpp>
#include <spine/schema_report.hpp>
#include <spine/version.hpp>

namespace spine {

Expand Down
12 changes: 12 additions & 0 deletions include/spine/version.hpp
Original file line number Diff line number Diff line change
@@ -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
5 changes: 5 additions & 0 deletions src/EGM.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
5 changes: 3 additions & 2 deletions src/schema_report.cpp
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
#include <spine/schema_report.hpp>
#include <spine/version.hpp>

#include <sstream>

Expand All @@ -17,8 +18,8 @@ void list(std::ostringstream& out, const char* label, const std::vector<std::str
std::string SchemaReport::summary() const {
std::ostringstream out;
out << path << "\n SPINE " << (spine_version.empty() ? "unknown" : spine_version)
<< ", format_version " << format_version << " (" << layout << "), read with model "
<< model_version << "\n";
<< ", format_version " << format_version << " (" << layout << "); read by spine-reader "
<< version() << " (model from SPINE " << model_version << ")\n";
for (const ProductReport& product : products) {
out << " " << product.product << " [" << product.class_name << "]: "
<< (product.complete() ? "all model fields read" : "some model fields missing") << "\n";
Expand Down
11 changes: 11 additions & 0 deletions src/version.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
#include <spine/version.hpp>

#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
13 changes: 12 additions & 1 deletion tests/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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=$<TARGET_FILE:spine-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()
26 changes: 23 additions & 3 deletions tests/check_spine_dump.cmake
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
# Runs spine-dump on the Reader test files and checks what it prints and returns.
# cmake -DSPINE_DUMP=<exe> -DDATA=<tests/data> -P check_spine_dump.cmake
# cmake -DSPINE_DUMP=<exe> -DDATA=<tests/data> -DREADER_VERSION=<X.Y.Z> -DMODEL_VERSION=<X.Y.Z>
# -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}
Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand Down
10 changes: 6 additions & 4 deletions tests/test_reader.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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());
Expand All @@ -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"));
Expand Down