From c7098577fc75e3fad2626317c1da2583d92124ac Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Mon, 12 Feb 2024 19:55:21 -0500
Subject: [PATCH 01/37] feat: run examples with `meson test`

---
 examples/meson.build | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/examples/meson.build b/examples/meson.build
index 6fe166d2..d43a98e6 100644
--- a/examples/meson.build
+++ b/examples/meson.build
@@ -22,7 +22,7 @@ endif
 
 # build executables
 foreach src : example_sources
-  executable(
+  exe = executable(
     src.split('.')[0],
     src,
     include_directories: project_inc,
@@ -31,6 +31,10 @@ foreach src : example_sources
     install:             true,
     install_rpath:       ':'.join(example_rpaths),
   )
+  test(src, exe,
+    args: ['data.hipo', '1000'],
+    workdir: get_option('prefix') / '..',
+  )
 endforeach
 
 # install config files

From 33c8952c9202d835c6652fd71a155302b936ed51 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Tue, 13 Feb 2024 14:33:24 -0500
Subject: [PATCH 02/37] feat: test algorithms automatically

---
 examples/meson.build              |  6 +---
 meson.build                       |  6 +++-
 meson.options                     |  8 +++--
 src/iguana/algorithms/meson.build | 11 ++++++
 src/iguana/tests/iguana-test.cc   | 58 +++++++++++++++++++++++++++++++
 src/iguana/tests/meson.build      | 25 +++++++++++++
 6 files changed, 105 insertions(+), 9 deletions(-)
 create mode 100644 src/iguana/tests/iguana-test.cc
 create mode 100644 src/iguana/tests/meson.build

diff --git a/examples/meson.build b/examples/meson.build
index d43a98e6..6fe166d2 100644
--- a/examples/meson.build
+++ b/examples/meson.build
@@ -22,7 +22,7 @@ endif
 
 # build executables
 foreach src : example_sources
-  exe = executable(
+  executable(
     src.split('.')[0],
     src,
     include_directories: project_inc,
@@ -31,10 +31,6 @@ foreach src : example_sources
     install:             true,
     install_rpath:       ':'.join(example_rpaths),
   )
-  test(src, exe,
-    args: ['data.hipo', '1000'],
-    workdir: get_option('prefix') / '..',
-  )
 endforeach
 
 # install config files
diff --git a/meson.build b/meson.build
index eeed83f5..293b1577 100644
--- a/meson.build
+++ b/meson.build
@@ -17,6 +17,10 @@ project(
 )
 project_description = 'Implementation Guardian of Analysis Algorithms'
 
+# meson modules
+pkg = import('pkgconfig')
+fs  = import('fs')
+
 # resolve dependencies
 # NOTE: those that are typically installed by package managers should use `meson/minimum-version.sh`
 fmt_dep = dependency(
@@ -71,6 +75,7 @@ add_project_arguments(
 # build and install shared libraries
 subdir('src/iguana/services')
 subdir('src/iguana/algorithms')
+subdir('src/iguana/tests')
 
 # build bindings
 if get_option('bind_python')
@@ -78,7 +83,6 @@ if get_option('bind_python')
 endif
 
 # generate pkg-config file
-pkg = import('pkgconfig')
 pkg.generate(
   name:        meson.project_name(),
   description: project_description,
diff --git a/meson.options b/meson.options
index 93858080..c128e1a8 100644
--- a/meson.options
+++ b/meson.options
@@ -1,3 +1,5 @@
-option('examples',      type: 'boolean', value: false, description: 'Build Iguana C++ examples')
-option('documentation', type: 'boolean', value: false, description: 'Generate API documentation (requires Doxygen)')
-option('bind_python',   type: 'boolean', value: false, description: 'Generate Python bindings and their examples')
+option('examples',        type: 'boolean', value: false, description: 'Build Iguana C++ examples')
+option('documentation',   type: 'boolean', value: false, description: 'Generate API documentation (requires Doxygen)')
+option('test_data_file',  type: 'string',  value: '',    description: 'Sample HIPO file for testing. Must be an absolute path or relative to the build directory. If unspecified, tests are not built')
+option('test_num_events', type: 'string',  value: '10',  description: 'Number of events from `test_data_file` to test')
+option('bind_python',     type: 'boolean', value: false, description: 'Generate Python bindings and their examples')
diff --git a/src/iguana/algorithms/meson.build b/src/iguana/algorithms/meson.build
index 2180c5cf..0ca46f61 100644
--- a/src/iguana/algorithms/meson.build
+++ b/src/iguana/algorithms/meson.build
@@ -1,3 +1,4 @@
+# algorithm source files
 algo_sources = [
   'Algorithm.cc',
   'AlgorithmFactory.cc',
@@ -8,6 +9,7 @@ algo_sources = [
   'clas12/LorentzTransformer.cc',
 ]
 
+# algorithm headers
 algo_public_headers = [
   'Algorithm.h',
   'AlgorithmBoilerplate.h',
@@ -19,10 +21,19 @@ algo_public_headers = [
   'clas12/LorentzTransformer.h',
 ]
 
+# algorithm configurations
 algo_config_dirs = [
   'clas12/config',
 ]
 
+# algorithm unique names and required banks, for those we want to test automatically
+algos_and_banks_for_unit_testing = {
+  'example::ExampleAlgorithm':  ['REC::Particle'],
+  'clas12::EventBuilderFilter': ['REC::Particle'],
+  'clas12::ZVertexFilter':      ['REC::Particle'],
+  'clas12::LorentzTransformer': ['REC::Particle'],
+}
+
 algo_lib = shared_library(
   'IguanaAlgorithms',
   algo_sources,
diff --git a/src/iguana/tests/iguana-test.cc b/src/iguana/tests/iguana-test.cc
new file mode 100644
index 00000000..f7a51799
--- /dev/null
+++ b/src/iguana/tests/iguana-test.cc
@@ -0,0 +1,58 @@
+#include <iguana/algorithms/AlgorithmSequence.h>
+#include <hipo4/reader.h>
+
+int main(int argc, char **argv) {
+
+  // parse arguments
+  if(argc-1 < 3) {
+    fmt::print(stderr, "USAGE: {} [data_file] [num_events] [algorithm_name] [banks]...\n", argv[0]);
+    return 2;
+  }
+  const std::string data_file  = std::string(argv[1]);
+  const int         num_events = std::stoi(argv[2]);
+  const std::string algo_name  = std::string(argv[3]);
+  std::vector<std::string> bank_names;
+  for(int i=4; i<argc; i++)
+    bank_names.push_back(std::string(argv[i]));
+  fmt::print("TEST IGUANA:\n");
+  fmt::print("  {:>20} = {}\n", "data_file", data_file);
+  fmt::print("  {:>20} = {}\n", "num_events", num_events);
+  fmt::print("  {:>20} = {}\n", "algo_name", algo_name);
+  fmt::print("  {:>20} = {}\n", "banks", fmt::join(bank_names,", "));
+  fmt::print("\n");
+
+  // open the HIPO file; we use 2 readers, one for 'before' (i.e., not passed through iguana), and one for 'after'
+  // (passed through iguana), so we may compare them
+  hipo::reader reader_before(data_file.c_str()); // NOTE: not copy-constructable, so make two separate readers
+  hipo::reader reader_after(data_file.c_str());
+  auto banks_before = reader_before.getBanks(bank_names);
+  auto banks_after  = reader_after.getBanks(bank_names);
+
+  // define the algorithm
+  iguana::AlgorithmSequence seq;
+  seq.Add(algo_name);
+  seq.SetOption(algo_name, "log", "debug");
+
+  // start the algorithm
+  seq.Start(banks_after);
+
+  // event loop
+  int it_ev = 0;
+  while(reader_after.next(banks_after) && (num_events==0 || it_ev++ < num_events)) {
+    // iterate the 'before' reader too
+    reader_before.next(banks_before);
+    // run the algorithm
+    seq.Run(banks_after);
+    // print the banks, before and after
+    for(decltype(bank_names)::size_type it_bank=0; it_bank < bank_names.size(); it_bank++) {
+      fmt::print("{:=^70}\n", fmt::format(" BEFORE: {} ", bank_names.at(it_bank)));
+      banks_before.at(it_bank).show();
+      fmt::print("{:=^70}\n", fmt::format(" AFTER: {} ", bank_names.at(it_bank)));
+      banks_after.at(it_bank).show();
+    }
+  }
+
+  // stop the algorithm
+  seq.Stop();
+  return 0;
+}
diff --git a/src/iguana/tests/meson.build b/src/iguana/tests/meson.build
new file mode 100644
index 00000000..afae5ad3
--- /dev/null
+++ b/src/iguana/tests/meson.build
@@ -0,0 +1,25 @@
+test_exe_name = 'iguana-test'
+
+test_exe = executable(
+  test_exe_name,
+  test_exe_name + '.cc',
+  include_directories: project_inc,
+  dependencies:        project_deps,
+  link_with:           project_libs,
+  install:             true,
+  # install_rpath:     # don't bother with rpath, since `meson test` will run it in the build directory
+)
+
+if fs.is_file(get_option('test_data_file'))
+  message('Test sample file provided; you may run tests with `meson test`')
+  foreach algo, banks : algos_and_banks_for_unit_testing
+    test(
+      test_exe_name + ' ' + algo.replace('::', '__'),
+      test_exe,
+      args: [ get_option('test_data_file'), get_option('test_num_events'), algo ] + banks,
+    )
+  endforeach
+else
+  stat_file = get_option('test_data_file')=='' ? 'provided' : 'found'
+  message('Test sample file NOT ' + stat_file + '; you may run tests manually with `' + test_exe_name + '`')
+endif

From 4f5452f174174c4904d762bfeb42e092e6891163 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Tue, 13 Feb 2024 14:48:54 -0500
Subject: [PATCH 03/37] ci: run new tests

---
 .github/workflows/ci.yml | 67 +++++++++++++++++++++++++---------------
 1 file changed, 42 insertions(+), 25 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index faeca294..21dcfbd4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -28,6 +28,25 @@ env:
 
 jobs:
 
+  # download test data
+  #########################################################
+
+  download_validation_files:
+    name: Download validation files
+    runs-on: ${{ inputs.runner }}
+    steps:
+      - name: download
+        run: wget --no-check-certificate http://clasweb.jlab.org/clas12offline/distribution/clas12-timeline/validation_files.tar.gz
+      - name: untar
+        run: tar xzvf validation_files.tar.gz
+      - name: select one file
+        run: mv -v $(find validation_files -type f -name "*.hipo" | head -n1) test_data.hipo
+      - uses: actions/upload-artifact@v4
+        with:
+          name: validation_files
+          retention-days: 1
+          path: test_data.hipo
+
   # dependencies
   #########################################################
 
@@ -65,6 +84,7 @@ jobs:
     name: Build Iguana
     needs:
       - build_hipo
+      - download_validation_files
     runs-on: ${{ inputs.runner }}
     container:
       image: ${{ inputs.container }}
@@ -82,6 +102,10 @@ jobs:
           clean: false
           fetch-tags: true
           fetch-depth: 0
+      - name: get test data
+        uses: actions/download-artifact@v4
+        with:
+          name: validation_files
       ### dependencies
       - name: install dependency packages
         run: .github/install-dependency-packages.sh ${{ inputs.runner }} ${{ inputs.verset }}
@@ -108,16 +132,23 @@ jobs:
         run: meson setup --native-file=native.ini build-iguana
       - name: meson configure
         run: |
-          meson configure              \
-            --prefix=$(pwd)/iguana     \
-            -Dexamples=True            \
-            -Ddocumentation=False      \
-            ${{ matrix.binding_opts }} \
+          meson configure                          \
+            --prefix=$(pwd)/iguana                 \
+            -Dexamples=True                        \
+            -Ddocumentation=False                  \
+            -Dtest_data_file=$(pwd)/test_data.hipo \
+            -Dtest_num_events=1000                 \
+            ${{ matrix.binding_opts }}             \
             build-iguana
       - name: dump build options
         run: meson configure build-iguana | cat
       - name: meson install
         run: meson install -C build-iguana
+      ### run tests
+      - name: run automatic tests
+        run: |
+          echo "NOTE: log files are found in artifact 'logs_build_iguana_${{ matrix.binding }}'"
+          meson test -C build-iguana
       ### dump info about this build
       - name: dump build log
         if: always()
@@ -151,31 +182,17 @@ jobs:
           name: build_iguana_${{ matrix.binding }}
           retention-days: 1
           path: iguana.tar.gz
-
-  # download test data
-  #########################################################
-
-  download_validation_files:
-    name: Download validation files
-    runs-on: ${{ inputs.runner }}
-    steps:
-      - name: download
-        run: wget --no-check-certificate http://clasweb.jlab.org/clas12offline/distribution/clas12-timeline/validation_files.tar.gz
-      - name: untar
-        run: tar xzvf validation_files.tar.gz
-      - name: select one file
-        run: mv -v $(find validation_files -type f -name "*.hipo" | head -n1) test_data.hipo
       - uses: actions/upload-artifact@v4
         with:
-          name: validation_files
-          retention-days: 1
-          path: test_data.hipo
+          name: logs_build_iguana_${{ matrix.binding }}
+          retention-days: 7
+          path: build-iguana/meson-logs
 
   # run tests
   #########################################################
 
-  test_iguana:
-    name: Test Iguana
+  test_examples:
+    name: Test Examples
     needs:
       - download_validation_files
       - build_iguana
@@ -345,7 +362,7 @@ jobs:
   final:
     name: Final
     needs:
-      - test_iguana
+      - test_examples
       - test_consumer_builds
     runs-on: ${{ inputs.runner }}
     steps:

From 393ebb05d36285e7f561c5521c50dfbd5116ffbf Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Tue, 13 Feb 2024 15:04:20 -0500
Subject: [PATCH 04/37] style: clarify job name

---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 21dcfbd4..a069818e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -81,7 +81,7 @@ jobs:
   #########################################################
 
   build_iguana:
-    name: Build Iguana
+    name: Build and Test Iguana
     needs:
       - build_hipo
       - download_validation_files

From 8d674e7630b6b4cd0fe24c2ef55be319364a1316 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Tue, 13 Feb 2024 16:49:42 -0500
Subject: [PATCH 05/37] ci: coverage tests

---
 .github/install-dependency-packages.sh |   2 +
 .github/workflows/ci.yml               | 156 +++++++++++++++++++------
 2 files changed, 123 insertions(+), 35 deletions(-)

diff --git a/.github/install-dependency-packages.sh b/.github/install-dependency-packages.sh
index f65e7dac..48c7514a 100755
--- a/.github/install-dependency-packages.sh
+++ b/.github/install-dependency-packages.sh
@@ -14,6 +14,7 @@ GENERAL_PACKAGE_LIST_LINUX=(
   pkgconf
   ninja
   meson
+  gcovr
 )
 IGUANA_PACKAGE_LIST_LINUX=(
   fmt
@@ -27,6 +28,7 @@ GENERAL_PACKAGE_LIST_MACOS=(
   tree
   ninja
   meson
+  gcovr
 )
 IGUANA_PACKAGE_LIST_MACOS=(
   fmt
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a069818e..835b201b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -73,7 +73,7 @@ jobs:
           tar czvf hipo{.tar.gz,}
       - uses: actions/upload-artifact@v4
         with:
-          name: build_deps_hipo
+          name: install_deps_hipo
           retention-days: 1
           path: hipo.tar.gz
 
@@ -81,10 +81,9 @@ jobs:
   #########################################################
 
   build_iguana:
-    name: Build and Test Iguana
+    name: Build Iguana
     needs:
       - build_hipo
-      - download_validation_files
     runs-on: ${{ inputs.runner }}
     container:
       image: ${{ inputs.container }}
@@ -102,17 +101,13 @@ jobs:
           clean: false
           fetch-tags: true
           fetch-depth: 0
-      - name: get test data
-        uses: actions/download-artifact@v4
-        with:
-          name: validation_files
       ### dependencies
       - name: install dependency packages
         run: .github/install-dependency-packages.sh ${{ inputs.runner }} ${{ inputs.verset }}
       - name: get local dependencies
         uses: actions/download-artifact@v4
         with:
-          pattern: build_deps_*
+          pattern: install_deps_*
           merge-multiple: true
       - name: untar local dependencies
         run: ls *.tar.gz | xargs -I{} tar xzvf {}
@@ -132,23 +127,16 @@ jobs:
         run: meson setup --native-file=native.ini build-iguana
       - name: meson configure
         run: |
-          meson configure                          \
-            --prefix=$(pwd)/iguana                 \
-            -Dexamples=True                        \
-            -Ddocumentation=False                  \
-            -Dtest_data_file=$(pwd)/test_data.hipo \
-            -Dtest_num_events=1000                 \
-            ${{ matrix.binding_opts }}             \
+          meson configure              \
+            --prefix=$(pwd)/iguana     \
+            -Dexamples=True            \
+            -Ddocumentation=False      \
+            ${{ matrix.binding_opts }} \
             build-iguana
       - name: dump build options
         run: meson configure build-iguana | cat
       - name: meson install
         run: meson install -C build-iguana
-      ### run tests
-      - name: run automatic tests
-        run: |
-          echo "NOTE: log files are found in artifact 'logs_build_iguana_${{ matrix.binding }}'"
-          meson test -C build-iguana
       ### dump info about this build
       - name: dump build log
         if: always()
@@ -176,21 +164,83 @@ jobs:
       - run: tree iguana
       ### upload artifacts
       - name: tar
-        run: tar czvf iguana{.tar.gz,}
+        run: |
+          tar czvf iguana{.tar.gz,}
+          tar czvf build-iguana{.tar.gz,}
       - uses: actions/upload-artifact@v4
         with:
-          name: build_iguana_${{ matrix.binding }}
+          name: install_iguana_${{ matrix.binding }}
           retention-days: 1
           path: iguana.tar.gz
       - uses: actions/upload-artifact@v4
+        if: ${{ matrix.binding == 'cpp' }}
         with:
-          name: logs_build_iguana_${{ matrix.binding }}
-          retention-days: 7
-          path: build-iguana/meson-logs
+          name: build_iguana_${{ matrix.binding }}
+          retention-days: 1
+          path: build-iguana.tar.gz
 
   # run tests
   #########################################################
 
+  test_iguana:
+    name: Test Iguana
+    needs:
+      - build_hipo
+      - download_validation_files
+    runs-on: ${{ inputs.runner }}
+    container:
+      image: ${{ inputs.container }}
+    steps:
+      ### setup
+      - uses: actions/checkout@v4
+        with: # settings needed for version number detection
+          clean: false
+          fetch-tags: true
+          fetch-depth: 0
+      - name: get test data
+        uses: actions/download-artifact@v4
+        with:
+          name: validation_files
+      - name: get iguana build dir
+        uses: actions/download-artifact@v4
+        with:
+          name: build_iguana_cpp
+      ### dependencies
+      - name: install dependency packages
+        run: .github/install-dependency-packages.sh ${{ inputs.runner }} ${{ inputs.verset }}
+      - name: get local dependencies
+        uses: actions/download-artifact@v4
+        with:
+          pattern: install_deps_*
+          merge-multiple: true
+      - name: untar local dependencies
+        run: ls *.tar.gz | xargs -I{} tar xzvf {}
+      ### re-build iguana
+      - name: meson configure
+        run: |
+          meson configure                          \
+            -Dtest_data_file=$(pwd)/test_data.hipo \
+            -Dtest_num_events=1000                 \
+            -Db_coverage=true                      \
+            build-iguana
+      - name: dump build options
+        run: meson configure build-iguana | cat
+      - name: meson install
+        run: meson install -C build-iguana
+      ### run tests
+      - name: TEST: automatic tests
+        run: |
+          echo -e "\e[1;31m[NOTE]: log files are found in artifact 'logs_build_iguana_${{ matrix.binding }}' \e[0m"
+          meson test -C build-iguana
+      - name: TEST: coverage
+        run: ninja -C build coverage
+      ### upload artifacts
+      - uses: actions/upload-artifact@v4
+        with:
+          name: logs_build_iguana_${{ matrix.binding }}
+          retention-days: 1
+          path: build-iguana/meson-logs
+
   test_examples:
     name: Test Examples
     needs:
@@ -217,12 +267,12 @@ jobs:
       - name: get dependency build artifacts
         uses: actions/download-artifact@v4
         with:
-          pattern: build_deps_*
+          pattern: install_deps_*
           merge-multiple: true
       - name: get iguana build artifacts
         uses: actions/download-artifact@v4
         with:
-          name: build_iguana_${{ matrix.binding }}
+          name: install_iguana_${{ matrix.binding }}
       - name: get test data
         uses: actions/download-artifact@v4
         with:
@@ -287,12 +337,12 @@ jobs:
       - name: get dependency build artifacts
         uses: actions/download-artifact@v4
         with:
-          pattern: build_deps_*
+          pattern: install_deps_*
           merge-multiple: true
       - name: get iguana build artifacts
         uses: actions/download-artifact@v4
         with:
-          name: build_iguana_cpp
+          name: install_iguana_cpp
       - name: get test data
         uses: actions/download-artifact@v4
         with:
@@ -326,7 +376,7 @@ jobs:
   #########################################################
 
   doc_generate:
-    if: ${{ inputs.runner == 'ubuntu-latest' }}
+    if: ${{ inputs.runner == 'ubuntu-latest' && inputs.verset == 'latest' }}
     name: Generate documentation
     runs-on: ${{ inputs.runner }}
     steps:
@@ -335,15 +385,50 @@ jobs:
         uses: mattnotmitt/doxygen-action@v1
         with:
           doxyfile-path: doc/Doxyfile
-      - uses: actions/upload-pages-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
+          name: doxygen
           retention-days: 1
           path: doc/api/
 
-  doc_deploy:
-    if: ${{ (github.head_ref == 'main' || github.ref_name == 'main') && inputs.runner == 'ubuntu-latest' }}
-    name: Deploy documentation
-    needs: doc_generate
+  # deployment
+  #########################################################
+
+  collect_webpages:
+    # if: ${{ (github.head_ref == 'main' || github.ref_name == 'main') && inputs.runner == 'ubuntu-latest' && inputs.verset == 'latest' }}
+    if: ${{ (github.head_ref == 'meson-test' || github.ref_name == 'meson-test') && inputs.runner == 'ubuntu-latest' && inputs.verset == 'latest' }}
+    name: Collect webpages
+    needs:
+      - doc_generate
+      - test_iguana
+    runs-on: ${{ inputs.runner }}
+    steps:
+      - name: download doxygen documentation
+        uses: actions/download-artifact@v4
+        with:
+          name: doxygen
+          path: doxygen
+      - name: download build logs
+        uses: actions/download-artifact@v4
+        with:
+          name: logs_build_iguana_cpp
+          path: build-iguana
+      - run: tree
+      - name: collect
+        run: |
+          mkdir pages
+          mv doxygen pages/
+          mv build-iguana/meson-logs/coveragereport pages/
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          retention-days: 1
+          path: pages/
+
+  deploy_webpages:
+    # if: ${{ (github.head_ref == 'main' || github.ref_name == 'main') && inputs.runner == 'ubuntu-latest' && inputs.verset == 'latest' }}
+    if: ${{ (github.head_ref == 'meson-test' || github.ref_name == 'meson-test') && inputs.runner == 'ubuntu-latest' && inputs.verset == 'latest' }}
+    name: Deploy webpages
+    needs: collect_webpages
     permissions:
       pages: write
       id-token: write
@@ -362,6 +447,7 @@ jobs:
   final:
     name: Final
     needs:
+      - test_iguana
       - test_examples
       - test_consumer_builds
     runs-on: ${{ inputs.runner }}

From 2f70d5c85185aa3848c1251a39719d14b2aa0263 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Tue, 13 Feb 2024 16:54:34 -0500
Subject: [PATCH 06/37] fix: syntax

---
 .github/workflows/ci.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 835b201b..b70ff42c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -228,11 +228,11 @@ jobs:
       - name: meson install
         run: meson install -C build-iguana
       ### run tests
-      - name: TEST: automatic tests
+      - name: TEST automatic tests
         run: |
           echo -e "\e[1;31m[NOTE]: log files are found in artifact 'logs_build_iguana_${{ matrix.binding }}' \e[0m"
           meson test -C build-iguana
-      - name: TEST: coverage
+      - name: TEST coverage
         run: ninja -C build coverage
       ### upload artifacts
       - uses: actions/upload-artifact@v4

From 9334cc20e3c4a7a076acaa2ba11d57a9cc0da0cf Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Tue, 13 Feb 2024 16:56:00 -0500
Subject: [PATCH 07/37] fix: `needs`

---
 .github/workflows/ci.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b70ff42c..29f35caf 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -187,6 +187,7 @@ jobs:
     needs:
       - build_hipo
       - download_validation_files
+      - build_iguana
     runs-on: ${{ inputs.runner }}
     container:
       image: ${{ inputs.container }}

From 1d92ae5c88ca3adf1b5eaf354a91b79961a57042 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Tue, 13 Feb 2024 17:04:18 -0500
Subject: [PATCH 08/37] fix: avoid native file and embed build opts

---
 .github/workflows/ci.yml | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 29f35caf..0f92a66e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -121,10 +121,8 @@ jobs:
           echo "| \`hipo\` | ${{ env.hipo_version }} |" >> $GITHUB_STEP_SUMMARY
           cat pkg_summary.md >> $GITHUB_STEP_SUMMARY
       ### build iguana
-      - name: resolve local dependencies
-        run: meson/resolve-dependencies.py --ini native.ini --hipo ./hipo
       - name: meson setup
-        run: meson setup --native-file=native.ini build-iguana
+        run: meson setup build-iguana $(meson/resolve-dependencies.py --cli --hipo ./hipo)
       - name: meson configure
         run: |
           meson configure              \

From 855d731614cb14de369d3d7200a5fa00de84e420 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Tue, 13 Feb 2024 17:09:58 -0500
Subject: [PATCH 09/37] fix: builddir and artifact names

---
 .github/workflows/ci.yml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0f92a66e..517fe698 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -229,14 +229,14 @@ jobs:
       ### run tests
       - name: TEST automatic tests
         run: |
-          echo -e "\e[1;31m[NOTE]: log files are found in artifact 'logs_build_iguana_${{ matrix.binding }}' \e[0m"
+          echo -e "\e[1;35m[NOTE]: log files are found in artifact 'logs_build_iguana' \e[0m"
           meson test -C build-iguana
       - name: TEST coverage
-        run: ninja -C build coverage
+        run: ninja -C build-iguana coverage
       ### upload artifacts
       - uses: actions/upload-artifact@v4
         with:
-          name: logs_build_iguana_${{ matrix.binding }}
+          name: logs_build_iguana
           retention-days: 1
           path: build-iguana/meson-logs
 
@@ -410,7 +410,7 @@ jobs:
       - name: download build logs
         uses: actions/download-artifact@v4
         with:
-          name: logs_build_iguana_cpp
+          name: logs_build_iguana
           path: build-iguana
       - run: tree
       - name: collect

From d6453105a337ecac0683ac12acb7a63c5960fec4 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Tue, 13 Feb 2024 17:56:48 -0500
Subject: [PATCH 10/37] fix: collector

---
 .github/install-dependency-packages.sh | 1 +
 .github/workflows/ci.yml               | 5 +++--
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/.github/install-dependency-packages.sh b/.github/install-dependency-packages.sh
index 48c7514a..138dab57 100755
--- a/.github/install-dependency-packages.sh
+++ b/.github/install-dependency-packages.sh
@@ -15,6 +15,7 @@ GENERAL_PACKAGE_LIST_LINUX=(
   ninja
   meson
   gcovr
+  python-pygments
 )
 IGUANA_PACKAGE_LIST_LINUX=(
   fmt
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 517fe698..15d926bd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -411,13 +411,14 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           name: logs_build_iguana
-          path: build-iguana
+          path: meson-logs
       - run: tree
       - name: collect
         run: |
           mkdir pages
           mv doxygen pages/
-          mv build-iguana/meson-logs/coveragereport pages/
+          mv meson-logs/coveragereport pages/
+      - run: tree
       - uses: actions/upload-pages-artifact@v3
         with:
           retention-days: 1

From 56b14a9119b54a16d301395727fcbd543af5dfb8 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Tue, 13 Feb 2024 18:15:33 -0500
Subject: [PATCH 11/37] feat: better reporting

---
 .github/pages-index.html | 13 +++++++++++++
 .github/workflows/ci.yml | 11 ++++++++++-
 README.md                |  5 ++++-
 3 files changed, 27 insertions(+), 2 deletions(-)
 create mode 100644 .github/pages-index.html

diff --git a/.github/pages-index.html b/.github/pages-index.html
new file mode 100644
index 00000000..53bdad1a
--- /dev/null
+++ b/.github/pages-index.html
@@ -0,0 +1,13 @@
+<!-- GitHub Pages Front Page -->
+<html>
+  <head>
+    <title>Iguana</title>
+  </head>
+  <body>
+    <h1>Iguana</h1>
+    <ul>
+      <li><a href="doxygen">API Documentation</a></li>
+      <li><a href="coveragereport">Coverage Report</a></li>
+    </ul>
+  </body>
+</html>
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 15d926bd..fe58c0fc 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -232,7 +232,12 @@ jobs:
           echo -e "\e[1;35m[NOTE]: log files are found in artifact 'logs_build_iguana' \e[0m"
           meson test -C build-iguana
       - name: TEST coverage
-        run: ninja -C build-iguana coverage
+        run: |
+          ninja -C build-iguana coverage
+          echo '### Coverage Report' >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          cat build-iguana/meson-logs/coverage.txt >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
       ### upload artifacts
       - uses: actions/upload-artifact@v4
         with:
@@ -402,6 +407,9 @@ jobs:
       - test_iguana
     runs-on: ${{ inputs.runner }}
     steps:
+      - uses: actions/checkout@v4
+        with:
+          path: iguana_src
       - name: download doxygen documentation
         uses: actions/download-artifact@v4
         with:
@@ -416,6 +424,7 @@ jobs:
       - name: collect
         run: |
           mkdir pages
+          cp iguana_src/.github/pages-index.html pages/
           mv doxygen pages/
           mv meson-logs/coveragereport pages/
       - run: tree
diff --git a/README.md b/README.md
index 7527d5b7..90a75195 100644
--- a/README.md
+++ b/README.md
@@ -3,9 +3,12 @@
 1. [Setup Guide](doc/setup.md)
 1. [Troubleshooting](doc/troubleshooting.md)
 1. [Design Notes](doc/design.md)
-1. [API documentation](https://jeffersonlab.github.io/iguana/)
+1. [API documentation](https://jeffersonlab.github.io/iguana/doxygen)
 1. [Developing a new Algorithm](src/iguana/algorithms/example/README.md)
 1. [Repository Maintenance](doc/maintenance.md)
 
+## Status
+1. [Coverage Report](https://jeffersonlab.github.io/iguana/coveragereport)
+
 > [!CAUTION]
 > This is still a _prototype_ design

From 3c58299926a8a73ab1b8d3d52648b1d9f6d05eae Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Tue, 13 Feb 2024 18:21:21 -0500
Subject: [PATCH 12/37] fix: minor fixes

---
 .github/workflows/ci.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index fe58c0fc..af5c128a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -114,6 +114,7 @@ jobs:
       - name: tree local dependencies
         run: tree hipo
       - name: summarize dependencies
+        if: ${{ matrix.binding == 'cpp' }}
         run: |
           echo '### Dependencies' >> $GITHUB_STEP_SUMMARY
           echo '| Dependency | Version |' >> $GITHUB_STEP_SUMMARY
@@ -424,7 +425,7 @@ jobs:
       - name: collect
         run: |
           mkdir pages
-          cp iguana_src/.github/pages-index.html pages/
+          cp iguana_src/.github/pages-index.html pages/index.html
           mv doxygen pages/
           mv meson-logs/coveragereport pages/
       - run: tree

From 4473795b15ef6bef713af993c2d789fd343ff6bb Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Wed, 14 Feb 2024 09:37:27 -0500
Subject: [PATCH 13/37] ci: clarify coverage report

---
 .github/install-dependency-packages.sh |  4 ++--
 .github/pages-index.html               |  2 +-
 .github/workflows/ci.yml               | 17 +++++++++++++----
 README.md                              |  2 +-
 4 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/.github/install-dependency-packages.sh b/.github/install-dependency-packages.sh
index 138dab57..89982c31 100755
--- a/.github/install-dependency-packages.sh
+++ b/.github/install-dependency-packages.sh
@@ -14,8 +14,8 @@ GENERAL_PACKAGE_LIST_LINUX=(
   pkgconf
   ninja
   meson
-  gcovr
-  python-pygments
+  gcovr # for coverage
+  python-pygments # for coverage report syntax colors
 )
 IGUANA_PACKAGE_LIST_LINUX=(
   fmt
diff --git a/.github/pages-index.html b/.github/pages-index.html
index 53bdad1a..51986a6f 100644
--- a/.github/pages-index.html
+++ b/.github/pages-index.html
@@ -7,7 +7,7 @@
     <h1>Iguana</h1>
     <ul>
       <li><a href="doxygen">API Documentation</a></li>
-      <li><a href="coveragereport">Coverage Report</a></li>
+      <li><a href="coverage-report">Coverage Report</a></li>
     </ul>
   </body>
 </html>
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index af5c128a..cad46492 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -235,16 +235,25 @@ jobs:
       - name: TEST coverage
         run: |
           ninja -C build-iguana coverage
+          mv build-iguana/meson-logs/coveragereport coverage-report
           echo '### Coverage Report' >> $GITHUB_STEP_SUMMARY
           echo '```' >> $GITHUB_STEP_SUMMARY
           cat build-iguana/meson-logs/coverage.txt >> $GITHUB_STEP_SUMMARY
           echo '```' >> $GITHUB_STEP_SUMMARY
+          echo '' >> $GITHUB_STEP_SUMMARY
+          echo '- for details, see the `coverage-report` artifact' >> $GITHUB_STEP_SUMMARY
+          echo '- to compare to the report from the `main` branch, see <https://jeffersonlab.github.io/iguana/coverage-report>' >> $GITHUB_STEP_SUMMARY
       ### upload artifacts
       - uses: actions/upload-artifact@v4
         with:
           name: logs_build_iguana
           retention-days: 1
           path: build-iguana/meson-logs
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          retention-days: 7
+          path: coverage-report
 
   test_examples:
     name: Test Examples
@@ -416,18 +425,18 @@ jobs:
         with:
           name: doxygen
           path: doxygen
-      - name: download build logs
+      - name: download coverage report
         uses: actions/download-artifact@v4
         with:
-          name: logs_build_iguana
-          path: meson-logs
+          name: coverage-report
+          path: coverage-report
       - run: tree
       - name: collect
         run: |
           mkdir pages
           cp iguana_src/.github/pages-index.html pages/index.html
           mv doxygen pages/
-          mv meson-logs/coveragereport pages/
+          mv coverage-report pages/
       - run: tree
       - uses: actions/upload-pages-artifact@v3
         with:
diff --git a/README.md b/README.md
index 90a75195..2e919099 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
 1. [Repository Maintenance](doc/maintenance.md)
 
 ## Status
-1. [Coverage Report](https://jeffersonlab.github.io/iguana/coveragereport)
+1. [Coverage Report](https://jeffersonlab.github.io/iguana/coverage-report)
 
 > [!CAUTION]
 > This is still a _prototype_ design

From 511b2b8790b1de1c1e67331d2e703b401ddd00fd Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Wed, 14 Feb 2024 10:35:46 -0500
Subject: [PATCH 14/37] feat: test `clang` build and sanitizers

---
 .github/workflows/ci.yml | 51 ++++++++++++++++++++++++++++++++++------
 1 file changed, 44 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cad46492..2a0779d8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -92,8 +92,12 @@ jobs:
       matrix:
         binding: [ cpp, python ]
         include:
-          - { binding: cpp,    binding_opts: ''                   }
-          - { binding: python, binding_opts: '-Dbind_python=True' }
+          - { binding: cpp,    CC: gcc,   CXX: g++,     binding_opts: ''                   }
+          - { binding: cpp,    CC: clang, CXX: clang++, binding_opts: ''                   }
+          - { binding: python, CC: gcc,   CXX: g++,     binding_opts: '-Dbind_python=True' }
+    env:
+      CC: ${{ matrix.CC }}
+      CXX: ${{ matrix.CXX }}
     steps:
       ### setup
       - uses: actions/checkout@v4
@@ -122,6 +126,12 @@ jobs:
           echo "| \`hipo\` | ${{ env.hipo_version }} |" >> $GITHUB_STEP_SUMMARY
           cat pkg_summary.md >> $GITHUB_STEP_SUMMARY
       ### build iguana
+      # - name: set compiler
+      #   run: |
+      #     echo CC=${{ matrix.CC }} >> $GITHUB_ENV
+      #     echo CXX=${{ matrix.CXX }} >> $GITHUB_ENV
+      - name: echo compiler
+        run: echo $CC, $CXX
       - name: meson setup
         run: meson setup build-iguana $(meson/resolve-dependencies.py --cli --hipo ./hipo)
       - name: meson configure
@@ -163,16 +173,18 @@ jobs:
       - run: tree iguana
       ### upload artifacts
       - name: tar
+        if: ${{ matrix.CC == 'gcc' }}
         run: |
           tar czvf iguana{.tar.gz,}
           tar czvf build-iguana{.tar.gz,}
       - uses: actions/upload-artifact@v4
+        if: ${{ matrix.CC == 'gcc' }}
         with:
           name: install_iguana_${{ matrix.binding }}
           retention-days: 1
           path: iguana.tar.gz
       - uses: actions/upload-artifact@v4
-        if: ${{ matrix.binding == 'cpp' }}
+        if: ${{ matrix.binding == 'cpp' && matrix.CC == 'gcc' }}
         with:
           name: build_iguana_${{ matrix.binding }}
           retention-days: 1
@@ -190,6 +202,23 @@ jobs:
     runs-on: ${{ inputs.runner }}
     container:
       image: ${{ inputs.container }}
+    strategy:
+      fail-fast: false
+      matrix:
+        mode:
+          - coverage
+          - san_address
+          - san_thread
+          - san_undefined
+          - san_memory
+          - san_leak
+        include:
+          - { mode: coverage,      CC: gcc, CXX: g++ }  # TODO: use clang or g++?
+          - { mode: san_address,   CC: gcc, CXX: g++ }
+          - { mode: san_thread,    CC: gcc, CXX: g++ }
+          - { mode: san_undefined, CC: gcc, CXX: g++ }
+          - { mode: san_memory,    CC: gcc, CXX: g++ }
+          - { mode: san_leak,      CC: gcc, CXX: g++ }
     steps:
       ### setup
       - uses: actions/checkout@v4
@@ -221,18 +250,24 @@ jobs:
           meson configure                          \
             -Dtest_data_file=$(pwd)/test_data.hipo \
             -Dtest_num_events=1000                 \
-            -Db_coverage=true                      \
             build-iguana
+          if [ "${{ matrix.mode }}" = "coverage" ]; then
+            meson configure build-iguana -Db_coverage=true
+          else
+            meson configure build-iguana -Db_sanitize=$(echo ${{ matrix.mode }} | sed 's;^san_;;')
+          fi
       - name: dump build options
         run: meson configure build-iguana | cat
       - name: meson install
         run: meson install -C build-iguana
       ### run tests
-      - name: TEST automatic tests
+      - name: TEST automatic tests and sanitizers
+        if: ${{ matrix.mode != 'coverage' }}
         run: |
-          echo -e "\e[1;35m[NOTE]: log files are found in artifact 'logs_build_iguana' \e[0m"
+          echo -e "\e[1;35m[NOTE]: log files are found in artifact 'logs_build_iguana_${{ matrix.mode }}' \e[0m"
           meson test -C build-iguana
       - name: TEST coverage
+        if: ${{ matrix.mode == 'coverage' }}
         run: |
           ninja -C build-iguana coverage
           mv build-iguana/meson-logs/coveragereport coverage-report
@@ -245,11 +280,13 @@ jobs:
           echo '- to compare to the report from the `main` branch, see <https://jeffersonlab.github.io/iguana/coverage-report>' >> $GITHUB_STEP_SUMMARY
       ### upload artifacts
       - uses: actions/upload-artifact@v4
+        if: ${{ matrix.mode != 'coverage' }}
         with:
-          name: logs_build_iguana
+          name: logs_build_iguana_${{ matrix.mode }}
           retention-days: 1
           path: build-iguana/meson-logs
       - uses: actions/upload-artifact@v4
+        if: ${{ matrix.mode == 'coverage' }}
         with:
           name: coverage-report
           retention-days: 7

From ce63877af37112f053798d2b1fba5cae027f09b2 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Wed, 14 Feb 2024 11:37:32 -0500
Subject: [PATCH 15/37] fix: proper compiler matrix

---
 .github/workflows/ci.yml | 41 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 21 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2a0779d8..16917f9a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -90,11 +90,14 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        binding: [ cpp, python ]
+        binding:
+          - cpp-gcc    # build C++-only version with both `g++` and `clang++`
+          - cpp-clang
+          - python
         include:
-          - { binding: cpp,    CC: gcc,   CXX: g++,     binding_opts: ''                   }
-          - { binding: cpp,    CC: clang, CXX: clang++, binding_opts: ''                   }
-          - { binding: python, CC: gcc,   CXX: g++,     binding_opts: '-Dbind_python=True' }
+          - { binding: cpp-gcc,   CC: gcc,   CXX: g++,     binding_opts: ''                   }
+          - { binding: cpp-clang, CC: clang, CXX: clang++, binding_opts: ''                   }
+          - { binding: python,    CC: gcc,   CXX: g++,     binding_opts: '-Dbind_python=True' }
     env:
       CC: ${{ matrix.CC }}
       CXX: ${{ matrix.CXX }}
@@ -118,18 +121,13 @@ jobs:
       - name: tree local dependencies
         run: tree hipo
       - name: summarize dependencies
-        if: ${{ matrix.binding == 'cpp' }}
+        if: ${{ matrix.binding == 'cpp-gcc' }}
         run: |
           echo '### Dependencies' >> $GITHUB_STEP_SUMMARY
           echo '| Dependency | Version |' >> $GITHUB_STEP_SUMMARY
           echo '| --- | --- |' >> $GITHUB_STEP_SUMMARY
           echo "| \`hipo\` | ${{ env.hipo_version }} |" >> $GITHUB_STEP_SUMMARY
           cat pkg_summary.md >> $GITHUB_STEP_SUMMARY
-      ### build iguana
-      # - name: set compiler
-      #   run: |
-      #     echo CC=${{ matrix.CC }} >> $GITHUB_ENV
-      #     echo CXX=${{ matrix.CXX }} >> $GITHUB_ENV
       - name: echo compiler
         run: echo $CC, $CXX
       - name: meson setup
@@ -151,7 +149,7 @@ jobs:
         if: always()
         run: cat build-iguana/meson-logs/meson-log.txt
       - name: readelf/otool iguana examples
-        if: ${{ matrix.binding == 'cpp' }}
+        if: ${{ matrix.binding == 'cpp-gcc' || matrix.binding == 'cpp-clang' }}
         run: |
           binaries=$(find iguana/bin -type f -name "iguana-example-*")
           libraries=$(find iguana -type f -name "*.so")
@@ -173,18 +171,16 @@ jobs:
       - run: tree iguana
       ### upload artifacts
       - name: tar
-        if: ${{ matrix.CC == 'gcc' }}
         run: |
           tar czvf iguana{.tar.gz,}
           tar czvf build-iguana{.tar.gz,}
       - uses: actions/upload-artifact@v4
-        if: ${{ matrix.CC == 'gcc' }}
         with:
           name: install_iguana_${{ matrix.binding }}
           retention-days: 1
           path: iguana.tar.gz
       - uses: actions/upload-artifact@v4
-        if: ${{ matrix.binding == 'cpp' && matrix.CC == 'gcc' }}
+        if: ${{ matrix.binding == 'cpp-gcc' || matrix.binding == 'cpp-clang' }}
         with:
           name: build_iguana_${{ matrix.binding }}
           retention-days: 1
@@ -219,6 +215,9 @@ jobs:
           - { mode: san_undefined, CC: gcc, CXX: g++ }
           - { mode: san_memory,    CC: gcc, CXX: g++ }
           - { mode: san_leak,      CC: gcc, CXX: g++ }
+    env:
+      CC: ${{ matrix.CC }}
+      CXX: ${{ matrix.CXX }}
     steps:
       ### setup
       - uses: actions/checkout@v4
@@ -233,7 +232,7 @@ jobs:
       - name: get iguana build dir
         uses: actions/download-artifact@v4
         with:
-          name: build_iguana_cpp
+          name: build_iguana_cpp-${{ matrix.CC }}
       ### dependencies
       - name: install dependency packages
         run: .github/install-dependency-packages.sh ${{ inputs.runner }} ${{ inputs.verset }}
@@ -303,10 +302,10 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        binding: [ cpp, python ]
+        binding: [ cpp-gcc, python ]
         include:
-          - { binding: cpp,    extension: ''    }
-          - { binding: python, extension: '.py' }
+          - { binding: cpp-cpp, extension: ''    }
+          - { binding: python,  extension: '.py' }
     steps:
       ### dependencies and test data
       - uses: actions/checkout@v4
@@ -363,10 +362,10 @@ jobs:
         run: iguana/bin/iguana-example-01-bank-rows${{ matrix.extension }} test_data.hipo ${{ env.num_events }}
       - name: test 02
         run: iguana/bin/iguana-example-02-YAMLReader${{ matrix.extension }}
-        if: ${{ matrix.binding == 'cpp' }} #FIXME
+        if: ${{ matrix.binding == 'cpp-gcc' }} #FIXME
       - name: test 03
         run: iguana/bin/iguana-example-03-zvertex-filter${{ matrix.extension }} test_data.hipo ${{ env.num_events }}
-        if: ${{ matrix.binding == 'cpp' }} #FIXME
+        if: ${{ matrix.binding == 'cpp-gcc' }} #FIXME
 
   test_consumer_builds:
     name: Test consumer builds
@@ -393,7 +392,7 @@ jobs:
       - name: get iguana build artifacts
         uses: actions/download-artifact@v4
         with:
-          name: install_iguana_cpp
+          name: install_iguana_cpp-gcc
       - name: get test data
         uses: actions/download-artifact@v4
         with:

From e145b4b6d5f75500d01c2efd634fb66474a45639 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Wed, 14 Feb 2024 11:43:23 -0500
Subject: [PATCH 16/37] fix: install `clang` on Arch

---
 .github/install-dependency-packages.sh | 1 +
 .github/workflows/ci.yml               | 2 --
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/.github/install-dependency-packages.sh b/.github/install-dependency-packages.sh
index 89982c31..2d03462a 100755
--- a/.github/install-dependency-packages.sh
+++ b/.github/install-dependency-packages.sh
@@ -8,6 +8,7 @@ set -e
 GENERAL_PACKAGE_LIST_LINUX=(
   python
   gcc
+  clang
   make
   cmake
   tree
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 16917f9a..b1bbdf15 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -128,8 +128,6 @@ jobs:
           echo '| --- | --- |' >> $GITHUB_STEP_SUMMARY
           echo "| \`hipo\` | ${{ env.hipo_version }} |" >> $GITHUB_STEP_SUMMARY
           cat pkg_summary.md >> $GITHUB_STEP_SUMMARY
-      - name: echo compiler
-        run: echo $CC, $CXX
       - name: meson setup
         run: meson setup build-iguana $(meson/resolve-dependencies.py --cli --hipo ./hipo)
       - name: meson configure

From b80996e0ffb9bda3a214de676e38152afd0aca48 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Wed, 14 Feb 2024 11:57:47 -0500
Subject: [PATCH 17/37] fix: force sanitizers to use `clang`

---
 .github/workflows/ci.yml | 13 +++----------
 1 file changed, 3 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b1bbdf15..304218ca 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -206,16 +206,9 @@ jobs:
           - san_undefined
           - san_memory
           - san_leak
-        include:
-          - { mode: coverage,      CC: gcc, CXX: g++ }  # TODO: use clang or g++?
-          - { mode: san_address,   CC: gcc, CXX: g++ }
-          - { mode: san_thread,    CC: gcc, CXX: g++ }
-          - { mode: san_undefined, CC: gcc, CXX: g++ }
-          - { mode: san_memory,    CC: gcc, CXX: g++ }
-          - { mode: san_leak,      CC: gcc, CXX: g++ }
     env:
-      CC: ${{ matrix.CC }}
-      CXX: ${{ matrix.CXX }}
+      CC: clang # prefer `clang` sanitizers
+      CXX: clang++
     steps:
       ### setup
       - uses: actions/checkout@v4
@@ -302,7 +295,7 @@ jobs:
       matrix:
         binding: [ cpp-gcc, python ]
         include:
-          - { binding: cpp-cpp, extension: ''    }
+          - { binding: cpp-gcc, extension: ''    }
           - { binding: python,  extension: '.py' }
     steps:
       ### dependencies and test data

From 7223499b5f449cfa8923ea46f85b77e6a9083c52 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Wed, 14 Feb 2024 12:01:34 -0500
Subject: [PATCH 18/37] fix: artifact name

---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 304218ca..909b2eb1 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -223,7 +223,7 @@ jobs:
       - name: get iguana build dir
         uses: actions/download-artifact@v4
         with:
-          name: build_iguana_cpp-${{ matrix.CC }}
+          name: build_iguana_cpp-${{ env.CC }}
       ### dependencies
       - name: install dependency packages
         run: .github/install-dependency-packages.sh ${{ inputs.runner }} ${{ inputs.verset }}

From e9904beafb54663b4d342ed0f2e76ccbe29c737a Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Wed, 14 Feb 2024 12:14:22 -0500
Subject: [PATCH 19/37] fix: install `gcc-libs`; compiler-dependent sanitizer;
 debug buildtype

---
 .github/install-dependency-packages.sh |  1 +
 .github/workflows/ci.yml               | 12 ++++++++++--
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/.github/install-dependency-packages.sh b/.github/install-dependency-packages.sh
index 2d03462a..e4b1cf67 100755
--- a/.github/install-dependency-packages.sh
+++ b/.github/install-dependency-packages.sh
@@ -8,6 +8,7 @@ set -e
 GENERAL_PACKAGE_LIST_LINUX=(
   python
   gcc
+  gcc-libs
   clang
   make
   cmake
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 909b2eb1..c24f2a5c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -134,6 +134,7 @@ jobs:
         run: |
           meson configure              \
             --prefix=$(pwd)/iguana     \
+            -Dbuildtype=debug          \
             -Dexamples=True            \
             -Ddocumentation=False      \
             ${{ matrix.binding_opts }} \
@@ -206,9 +207,16 @@ jobs:
           - san_undefined
           - san_memory
           - san_leak
+        include:
+          - { mode: coverage,      CC: gcc,   CXX: g++     }
+          - { mode: san_address,   CC: clang, CXX: clang++ }
+          - { mode: san_thread,    CC: clang, CXX: clang++ }
+          - { mode: san_undefined, CC: clang, CXX: clang++ }
+          - { mode: san_memory,    CC: clang, CXX: clang++ }
+          - { mode: san_leak,      CC: clang, CXX: clang++ }
     env:
-      CC: clang # prefer `clang` sanitizers
-      CXX: clang++
+      CC: ${{ matrix.CC }}
+      CXX: ${{ matrix.CXX }}
     steps:
       ### setup
       - uses: actions/checkout@v4

From 379cababc066e6bf75876d75b87e8680170ee97b Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Wed, 14 Feb 2024 15:29:50 -0500
Subject: [PATCH 20/37] fix: run tests before coverage target

---
 .github/install-dependency-packages.sh | 1 -
 .github/workflows/ci.yml               | 1 -
 2 files changed, 2 deletions(-)

diff --git a/.github/install-dependency-packages.sh b/.github/install-dependency-packages.sh
index e4b1cf67..2d03462a 100755
--- a/.github/install-dependency-packages.sh
+++ b/.github/install-dependency-packages.sh
@@ -8,7 +8,6 @@ set -e
 GENERAL_PACKAGE_LIST_LINUX=(
   python
   gcc
-  gcc-libs
   clang
   make
   cmake
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c24f2a5c..1de4181f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -260,7 +260,6 @@ jobs:
         run: meson install -C build-iguana
       ### run tests
       - name: TEST automatic tests and sanitizers
-        if: ${{ matrix.mode != 'coverage' }}
         run: |
           echo -e "\e[1;35m[NOTE]: log files are found in artifact 'logs_build_iguana_${{ matrix.mode }}' \e[0m"
           meson test -C build-iguana

From 39c00067569e30a40c30c745c16bc683526817ef Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Wed, 14 Feb 2024 16:57:55 -0500
Subject: [PATCH 21/37] ci: buildtype matrix

---
 .github/workflows/ci.yml | 81 +++++++++++++++++++++++-----------------
 1 file changed, 46 insertions(+), 35 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1de4181f..50e30be6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -88,16 +88,22 @@ jobs:
     container:
       image: ${{ inputs.container }}
     strategy:
-      fail-fast: false
+      fail-fast: true
       matrix:
-        binding:
-          - cpp-gcc    # build C++-only version with both `g++` and `clang++`
-          - cpp-clang
+        id:
+          # build C++-only version with various compilers and buildtypes
+          - cpp-gcc-release
+          - cpp-gcc-debug
+          - cpp-clang-release
+          - cpp-clang-debug
+          # build with bindings
           - python
         include:
-          - { binding: cpp-gcc,   CC: gcc,   CXX: g++,     binding_opts: ''                   }
-          - { binding: cpp-clang, CC: clang, CXX: clang++, binding_opts: ''                   }
-          - { binding: python,    CC: gcc,   CXX: g++,     binding_opts: '-Dbind_python=True' }
+          - { id: cpp-gcc-release,   CC: gcc,   CXX: g++,     buildtype: release, binding_opts: ''                   }
+          - { id: cpp-gcc-debug,     CC: gcc,   CXX: g++,     buildtype: debug,   binding_opts: ''                   }
+          - { id: cpp-clang-release, CC: clang, CXX: clang++, buildtype: release, binding_opts: ''                   }
+          - { id: cpp-clang-debug,   CC: clang, CXX: clang++, buildtype: debug,   binding_opts: ''                   }
+          - { id: python,            CC: gcc,   CXX: g++,     buildtype: release, binding_opts: '-Dbind_python=True' }
     env:
       CC: ${{ matrix.CC }}
       CXX: ${{ matrix.CXX }}
@@ -121,7 +127,7 @@ jobs:
       - name: tree local dependencies
         run: tree hipo
       - name: summarize dependencies
-        if: ${{ matrix.binding == 'cpp-gcc' }}
+        if: ${{ matrix.id == 'cpp-gcc-release' }}
         run: |
           echo '### Dependencies' >> $GITHUB_STEP_SUMMARY
           echo '| Dependency | Version |' >> $GITHUB_STEP_SUMMARY
@@ -132,12 +138,12 @@ jobs:
         run: meson setup build-iguana $(meson/resolve-dependencies.py --cli --hipo ./hipo)
       - name: meson configure
         run: |
-          meson configure              \
-            --prefix=$(pwd)/iguana     \
-            -Dbuildtype=debug          \
-            -Dexamples=True            \
-            -Ddocumentation=False      \
-            ${{ matrix.binding_opts }} \
+          meson configure                       \
+            --prefix=$(pwd)/iguana              \
+            -Dbuildtype=${{ matrix.buildtype }} \
+            -Dexamples=True                     \
+            -Ddocumentation=False               \
+            ${{ matrix.binding_opts }}          \
             build-iguana
       - name: dump build options
         run: meson configure build-iguana | cat
@@ -148,7 +154,7 @@ jobs:
         if: always()
         run: cat build-iguana/meson-logs/meson-log.txt
       - name: readelf/otool iguana examples
-        if: ${{ matrix.binding == 'cpp-gcc' || matrix.binding == 'cpp-clang' }}
+        if: ${{ matrix.id == 'cpp-gcc-release' || matrix.id == 'cpp-gcc-debug' || matrix.id == 'cpp-clang-release' || matrix.id == 'cpp-clang-debug' }}
         run: |
           binaries=$(find iguana/bin -type f -name "iguana-example-*")
           libraries=$(find iguana -type f -name "*.so")
@@ -175,13 +181,13 @@ jobs:
           tar czvf build-iguana{.tar.gz,}
       - uses: actions/upload-artifact@v4
         with:
-          name: install_iguana_${{ matrix.binding }}
+          name: install_iguana_${{ matrix.id }}
           retention-days: 1
           path: iguana.tar.gz
       - uses: actions/upload-artifact@v4
-        if: ${{ matrix.binding == 'cpp-gcc' || matrix.binding == 'cpp-clang' }}
+        if: ${{ matrix.id == 'cpp-gcc-release' || matrix.id == 'cpp-gcc-debug' || matrix.id == 'cpp-clang-release' || matrix.id == 'cpp-clang-debug' }}
         with:
-          name: build_iguana_${{ matrix.binding }}
+          name: build_iguana_${{ matrix.id }}
           retention-days: 1
           path: build-iguana.tar.gz
 
@@ -208,15 +214,16 @@ jobs:
           - san_memory
           - san_leak
         include:
-          - { mode: coverage,      CC: gcc,   CXX: g++     }
-          - { mode: san_address,   CC: clang, CXX: clang++ }
-          - { mode: san_thread,    CC: clang, CXX: clang++ }
-          - { mode: san_undefined, CC: clang, CXX: clang++ }
-          - { mode: san_memory,    CC: clang, CXX: clang++ }
-          - { mode: san_leak,      CC: clang, CXX: clang++ }
+          - { mode: coverage,      CC: gcc,   CXX: g++,     buildtype: release }
+          - { mode: san_address,   CC: clang, CXX: clang++, buildtype: release }
+          - { mode: san_thread,    CC: clang, CXX: clang++, buildtype: release }
+          - { mode: san_undefined, CC: clang, CXX: clang++, buildtype: release }
+          - { mode: san_memory,    CC: clang, CXX: clang++, buildtype: release }
+          - { mode: san_leak,      CC: clang, CXX: clang++, buildtype: release }
     env:
       CC: ${{ matrix.CC }}
       CXX: ${{ matrix.CXX }}
+      build_id: ${{ matrix.CC }}-${{ matrix.buildtype }}
     steps:
       ### setup
       - uses: actions/checkout@v4
@@ -231,7 +238,7 @@ jobs:
       - name: get iguana build dir
         uses: actions/download-artifact@v4
         with:
-          name: build_iguana_cpp-${{ env.CC }}
+          name: build_iguana_cpp-${{ env.build_id }}
       ### dependencies
       - name: install dependency packages
         run: .github/install-dependency-packages.sh ${{ inputs.runner }} ${{ inputs.verset }}
@@ -300,10 +307,12 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        binding: [ cpp-gcc, python ]
+        id:
+          - cpp-gcc-release
+          - python
         include:
-          - { binding: cpp-gcc, extension: ''    }
-          - { binding: python,  extension: '.py' }
+          - { id: cpp-gcc-release, extension: ''    }
+          - { id: python,          extension: '.py' }
     steps:
       ### dependencies and test data
       - uses: actions/checkout@v4
@@ -320,7 +329,7 @@ jobs:
       - name: get iguana build artifacts
         uses: actions/download-artifact@v4
         with:
-          name: install_iguana_${{ matrix.binding }}
+          name: install_iguana_${{ matrix.id }}
       - name: get test data
         uses: actions/download-artifact@v4
         with:
@@ -333,7 +342,7 @@ jobs:
         run: tree
       ### setup python virtaul environment (for python binding tests)
       - name: install python binding runtime dependencies
-        if: ${{ matrix.binding == 'python' }}
+        if: ${{ matrix.id == 'python' }}
         run: |
           python -m venv .venv
           source .venv/bin/activate
@@ -341,13 +350,13 @@ jobs:
           python -m pip install -r iguana_src/bind/python/requirements.txt
       ### set env vars - depends on runner and binding
       - name: source environment for Linux and python
-        if: ${{ inputs.runner == 'ubuntu-latest' && matrix.binding == 'python' }}
+        if: ${{ inputs.runner == 'ubuntu-latest' && matrix.id == 'python' }}
         run: |
           source iguana/bin/this_iguana.sh verbose
           echo PKG_CONFIG_PATH=$PKG_CONFIG_PATH >> $GITHUB_ENV
           echo PYTHONPATH=$PYTHONPATH           >> $GITHUB_ENV
       - name: source environment for macOS and python
-        if: ${{ inputs.runner == 'macos-latest' && matrix.binding == 'python' }}
+        if: ${{ inputs.runner == 'macos-latest' && matrix.id == 'python' }}
         run: |
           source iguana/bin/this_iguana.sh verbose ld
           echo PKG_CONFIG_PATH=$PKG_CONFIG_PATH     >> $GITHUB_ENV
@@ -360,10 +369,10 @@ jobs:
         run: iguana/bin/iguana-example-01-bank-rows${{ matrix.extension }} test_data.hipo ${{ env.num_events }}
       - name: test 02
         run: iguana/bin/iguana-example-02-YAMLReader${{ matrix.extension }}
-        if: ${{ matrix.binding == 'cpp-gcc' }} #FIXME
+        if: ${{ matrix.id == 'cpp-gcc-release' }} #FIXME
       - name: test 03
         run: iguana/bin/iguana-example-03-zvertex-filter${{ matrix.extension }} test_data.hipo ${{ env.num_events }}
-        if: ${{ matrix.binding == 'cpp-gcc' }} #FIXME
+        if: ${{ matrix.id == 'cpp-gcc-release' }} #FIXME
 
   test_consumer_builds:
     name: Test consumer builds
@@ -377,6 +386,8 @@ jobs:
       fail-fast: false
       matrix:
         tool: [ cmake, make, meson ]
+    env:
+      build_id: cpp-gcc-release
     steps:
       ### dependencies and test data
       - uses: actions/checkout@v4
@@ -390,7 +401,7 @@ jobs:
       - name: get iguana build artifacts
         uses: actions/download-artifact@v4
         with:
-          name: install_iguana_cpp-gcc
+          name: install_iguana_${{ env.build_id }}
       - name: get test data
         uses: actions/download-artifact@v4
         with:

From 537f71183548814ab94a571dc3a98f95a0f9b496 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Wed, 14 Feb 2024 17:38:10 -0500
Subject: [PATCH 22/37] fix: `b_lundef` must be false for `clang` sanitizers

---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 50e30be6..cf0fbbe4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -259,7 +259,7 @@ jobs:
           if [ "${{ matrix.mode }}" = "coverage" ]; then
             meson configure build-iguana -Db_coverage=true
           else
-            meson configure build-iguana -Db_sanitize=$(echo ${{ matrix.mode }} | sed 's;^san_;;')
+            meson configure build-iguana -Db_sanitize=$(echo ${{ matrix.mode }} | sed 's;^san_;;') -Db_lundef=false
           fi
       - name: dump build options
         run: meson configure build-iguana | cat

From 97a9545880c2b58bca9ce29dcea688481bb28aaa Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Wed, 14 Feb 2024 17:56:19 -0500
Subject: [PATCH 23/37] style: clearer build options

---
 .github/workflows/ci.yml | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cf0fbbe4..5f67fe72 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -257,9 +257,15 @@ jobs:
             -Dtest_num_events=1000                 \
             build-iguana
           if [ "${{ matrix.mode }}" = "coverage" ]; then
-            meson configure build-iguana -Db_coverage=true
+            meson configure     \
+              -Db_coverage=true \
+              build-iguana
           else
-            meson configure build-iguana -Db_sanitize=$(echo ${{ matrix.mode }} | sed 's;^san_;;') -Db_lundef=false
+            san=$(echo ${{ matrix.mode }} | sed 's;^san_;;')
+            meson configure     \
+              -Db_sanitize=$san \
+              -Db_lundef=false  \
+              build-iguana
           fi
       - name: dump build options
         run: meson configure build-iguana | cat

From 0d61e4bf997199a90191827635997f5673a22e37 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Wed, 14 Feb 2024 18:25:12 -0500
Subject: [PATCH 24/37] ci: sanitize on debug build and print error logs

---
 .github/workflows/ci.yml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5f67fe72..6494d1dd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -215,11 +215,11 @@ jobs:
           - san_leak
         include:
           - { mode: coverage,      CC: gcc,   CXX: g++,     buildtype: release }
-          - { mode: san_address,   CC: clang, CXX: clang++, buildtype: release }
-          - { mode: san_thread,    CC: clang, CXX: clang++, buildtype: release }
-          - { mode: san_undefined, CC: clang, CXX: clang++, buildtype: release }
-          - { mode: san_memory,    CC: clang, CXX: clang++, buildtype: release }
-          - { mode: san_leak,      CC: clang, CXX: clang++, buildtype: release }
+          - { mode: san_address,   CC: clang, CXX: clang++, buildtype: debug   }
+          - { mode: san_thread,    CC: clang, CXX: clang++, buildtype: debug   }
+          - { mode: san_undefined, CC: clang, CXX: clang++, buildtype: debug   }
+          - { mode: san_memory,    CC: clang, CXX: clang++, buildtype: debug   }
+          - { mode: san_leak,      CC: clang, CXX: clang++, buildtype: debug   }
     env:
       CC: ${{ matrix.CC }}
       CXX: ${{ matrix.CXX }}
@@ -275,7 +275,7 @@ jobs:
       - name: TEST automatic tests and sanitizers
         run: |
           echo -e "\e[1;35m[NOTE]: log files are found in artifact 'logs_build_iguana_${{ matrix.mode }}' \e[0m"
-          meson test -C build-iguana
+          meson test --print-errorlogs -C build-iguana
       - name: TEST coverage
         if: ${{ matrix.mode == 'coverage' }}
         run: |

From 964c4a7a88ecbc35760de9ca5a90d073e9649cd9 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Wed, 14 Feb 2024 18:55:10 -0500
Subject: [PATCH 25/37] fix: disable memory sanitizer for now

---
 .github/workflows/ci.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6494d1dd..e2b69aab 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -211,14 +211,14 @@ jobs:
           - san_address
           - san_thread
           - san_undefined
-          - san_memory
+          # - san_memory  # FIXME: not sure how to get meaningful stack traces
           - san_leak
         include:
           - { mode: coverage,      CC: gcc,   CXX: g++,     buildtype: release }
           - { mode: san_address,   CC: clang, CXX: clang++, buildtype: debug   }
           - { mode: san_thread,    CC: clang, CXX: clang++, buildtype: debug   }
           - { mode: san_undefined, CC: clang, CXX: clang++, buildtype: debug   }
-          - { mode: san_memory,    CC: clang, CXX: clang++, buildtype: debug   }
+          # - { mode: san_memory,    CC: clang, CXX: clang++, buildtype: debug   }
           - { mode: san_leak,      CC: clang, CXX: clang++, buildtype: debug   }
     env:
       CC: ${{ matrix.CC }}

From 0a5627020351bef826079ea1db7eb031d3c37855 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Fri, 16 Feb 2024 11:19:43 -0500
Subject: [PATCH 26/37] ci: install `llvm`; use JSON matrix for testing; test
 leak sanitizer

---
 .github/install-dependency-packages.sh        |  3 +-
 .github/workflows/ci.yml                      | 50 +++++++++++++------
 .../algorithms/clas12/LorentzTransformer.cc   |  1 +
 src/iguana/tests/iguana-test.cc               | 27 ++++++----
 4 files changed, 54 insertions(+), 27 deletions(-)

diff --git a/.github/install-dependency-packages.sh b/.github/install-dependency-packages.sh
index 2d03462a..444b872f 100755
--- a/.github/install-dependency-packages.sh
+++ b/.github/install-dependency-packages.sh
@@ -15,8 +15,9 @@ GENERAL_PACKAGE_LIST_LINUX=(
   pkgconf
   ninja
   meson
-  gcovr # for coverage
+  gcovr           # for coverage
   python-pygments # for coverage report syntax colors
+  llvm            # for `llvm-symbolizer`, for human-readable sanitizer results
 )
 IGUANA_PACKAGE_LIST_LINUX=(
   fmt
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e2b69aab..bb270aa6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -17,6 +17,40 @@ on:
         required: false
         type: string
         default: 'latest'
+      test_matrix:
+        description: 'Test matrix for `test_iguana` job (JSON)'
+        required: false
+        type: string
+        default: >-
+          {
+            "include": [
+              { "mode": "coverage",      "CC": "gcc",   "CXX": "g++",     "buildtype": "release" },
+              { "mode": "san_address",   "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
+              { "mode": "san_thread",    "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
+              { "mode": "san_undefined", "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
+              { "mode": "san_memory",    "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
+              { "mode": "san_leak",      "CC": "clang", "CXX": "clang++", "buildtype": "debug"   }
+            ]
+          }
+        # default: >-
+        #   {
+        #     "mode": [
+        #       "coverage",
+        #       "san_address",
+        #       "san_thread",
+        #       "san_undefined",
+        #       "san_memory",
+        #       "san_leak"
+        #     ],
+        #     "include": [
+        #       { "mode": "coverage",      "CC": "gcc",   "CXX": "g++",     "buildtype": "release" },
+        #       { "mode": "san_address",   "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
+        #       { "mode": "san_thread",    "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
+        #       { "mode": "san_undefined", "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
+        #       { "mode": "san_memory",    "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
+        #       { "mode": "san_leak",      "CC": "clang", "CXX": "clang++", "buildtype": "debug"   }
+        #     ]
+        #   }
 
 defaults:
   run:
@@ -205,21 +239,7 @@ jobs:
       image: ${{ inputs.container }}
     strategy:
       fail-fast: false
-      matrix:
-        mode:
-          - coverage
-          - san_address
-          - san_thread
-          - san_undefined
-          # - san_memory  # FIXME: not sure how to get meaningful stack traces
-          - san_leak
-        include:
-          - { mode: coverage,      CC: gcc,   CXX: g++,     buildtype: release }
-          - { mode: san_address,   CC: clang, CXX: clang++, buildtype: debug   }
-          - { mode: san_thread,    CC: clang, CXX: clang++, buildtype: debug   }
-          - { mode: san_undefined, CC: clang, CXX: clang++, buildtype: debug   }
-          # - { mode: san_memory,    CC: clang, CXX: clang++, buildtype: debug   }
-          - { mode: san_leak,      CC: clang, CXX: clang++, buildtype: debug   }
+      matrix: ${{ fromJson(inputs.test_matrix) }}
     env:
       CC: ${{ matrix.CC }}
       CXX: ${{ matrix.CXX }}
diff --git a/src/iguana/algorithms/clas12/LorentzTransformer.cc b/src/iguana/algorithms/clas12/LorentzTransformer.cc
index 60125388..bdb17c10 100644
--- a/src/iguana/algorithms/clas12/LorentzTransformer.cc
+++ b/src/iguana/algorithms/clas12/LorentzTransformer.cc
@@ -26,6 +26,7 @@ namespace iguana::clas12 {
 
 
   void LorentzTransformer::Run(hipo::banklist& banks) const {
+    auto leak = new Object("leak");
     auto& particleBank = GetBank(banks, b_particle, "REC::Particle");
     ShowBank(particleBank, Logger::Header("INPUT PARTICLES"));
     for(int row = 0; row < particleBank.getRows(); row++) {
diff --git a/src/iguana/tests/iguana-test.cc b/src/iguana/tests/iguana-test.cc
index f7a51799..be9f538c 100644
--- a/src/iguana/tests/iguana-test.cc
+++ b/src/iguana/tests/iguana-test.cc
@@ -12,14 +12,17 @@ int main(int argc, char **argv) {
   const int         num_events = std::stoi(argv[2]);
   const std::string algo_name  = std::string(argv[3]);
   std::vector<std::string> bank_names;
+  bool verbose = false;
   for(int i=4; i<argc; i++)
     bank_names.push_back(std::string(argv[i]));
-  fmt::print("TEST IGUANA:\n");
-  fmt::print("  {:>20} = {}\n", "data_file", data_file);
-  fmt::print("  {:>20} = {}\n", "num_events", num_events);
-  fmt::print("  {:>20} = {}\n", "algo_name", algo_name);
-  fmt::print("  {:>20} = {}\n", "banks", fmt::join(bank_names,", "));
-  fmt::print("\n");
+  if(verbose) {
+    fmt::print("TEST IGUANA:\n");
+    fmt::print("  {:>20} = {}\n", "data_file", data_file);
+    fmt::print("  {:>20} = {}\n", "num_events", num_events);
+    fmt::print("  {:>20} = {}\n", "algo_name", algo_name);
+    fmt::print("  {:>20} = {}\n", "banks", fmt::join(bank_names,", "));
+    fmt::print("\n");
+  }
 
   // open the HIPO file; we use 2 readers, one for 'before' (i.e., not passed through iguana), and one for 'after'
   // (passed through iguana), so we may compare them
@@ -44,11 +47,13 @@ int main(int argc, char **argv) {
     // run the algorithm
     seq.Run(banks_after);
     // print the banks, before and after
-    for(decltype(bank_names)::size_type it_bank=0; it_bank < bank_names.size(); it_bank++) {
-      fmt::print("{:=^70}\n", fmt::format(" BEFORE: {} ", bank_names.at(it_bank)));
-      banks_before.at(it_bank).show();
-      fmt::print("{:=^70}\n", fmt::format(" AFTER: {} ", bank_names.at(it_bank)));
-      banks_after.at(it_bank).show();
+    if(verbose) {
+      for(decltype(bank_names)::size_type it_bank=0; it_bank < bank_names.size(); it_bank++) {
+        fmt::print("{:=^70}\n", fmt::format(" BEFORE: {} ", bank_names.at(it_bank)));
+        banks_before.at(it_bank).show();
+        fmt::print("{:=^70}\n", fmt::format(" AFTER: {} ", bank_names.at(it_bank)));
+        banks_after.at(it_bank).show();
+      }
     }
   }
 

From 4ee1dadd57ef60c801be0902d7a4d87428fad52e Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Fri, 16 Feb 2024 11:31:57 -0500
Subject: [PATCH 27/37] ci: don't run coverage and sanitizers for `macOS` or
 `MinVer`

---
 .github/workflows/ci.yml     | 52 +++++++++++++++---------------------
 .github/workflows/macos.yml  |  6 +++++
 .github/workflows/minver.yml |  6 +++++
 3 files changed, 33 insertions(+), 31 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index bb270aa6..9de16c83 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,25 +32,6 @@ on:
               { "mode": "san_leak",      "CC": "clang", "CXX": "clang++", "buildtype": "debug"   }
             ]
           }
-        # default: >-
-        #   {
-        #     "mode": [
-        #       "coverage",
-        #       "san_address",
-        #       "san_thread",
-        #       "san_undefined",
-        #       "san_memory",
-        #       "san_leak"
-        #     ],
-        #     "include": [
-        #       { "mode": "coverage",      "CC": "gcc",   "CXX": "g++",     "buildtype": "release" },
-        #       { "mode": "san_address",   "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
-        #       { "mode": "san_thread",    "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
-        #       { "mode": "san_undefined", "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
-        #       { "mode": "san_memory",    "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
-        #       { "mode": "san_leak",      "CC": "clang", "CXX": "clang++", "buildtype": "debug"   }
-        #     ]
-        #   }
 
 defaults:
   run:
@@ -276,23 +257,26 @@ jobs:
             -Dtest_data_file=$(pwd)/test_data.hipo \
             -Dtest_num_events=1000                 \
             build-iguana
-          if [ "${{ matrix.mode }}" = "coverage" ]; then
-            meson configure     \
-              -Db_coverage=true \
-              build-iguana
-          else
-            san=$(echo ${{ matrix.mode }} | sed 's;^san_;;')
-            meson configure     \
-              -Db_sanitize=$san \
-              -Db_lundef=false  \
-              build-iguana
-          fi
+          case ${{ matrix.mode }} in
+            coverage)
+              meson configure     \
+                -Db_coverage=true \
+                build-iguana
+              ;;
+            san_*)
+              san=$(echo ${{ matrix.mode }} | sed 's;^san_;;')
+              meson configure     \
+                -Db_sanitize=$san \
+                -Db_lundef=false  \
+                build-iguana
+              ;;
+          esac
       - name: dump build options
         run: meson configure build-iguana | cat
       - name: meson install
         run: meson install -C build-iguana
       ### run tests
-      - name: TEST automatic tests and sanitizers
+      - name: TEST algorithms
         run: |
           echo -e "\e[1;35m[NOTE]: log files are found in artifact 'logs_build_iguana_${{ matrix.mode }}' \e[0m"
           meson test --print-errorlogs -C build-iguana
@@ -322,6 +306,9 @@ jobs:
           retention-days: 7
           path: coverage-report
 
+  # run examples
+  #########################################################
+
   test_examples:
     name: Test Examples
     needs:
@@ -400,6 +387,9 @@ jobs:
         run: iguana/bin/iguana-example-03-zvertex-filter${{ matrix.extension }} test_data.hipo ${{ env.num_events }}
         if: ${{ matrix.id == 'cpp-gcc-release' }} #FIXME
 
+  # test consumers
+  #########################################################
+
   test_consumer_builds:
     name: Test consumer builds
     needs:
diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml
index 7ceedd0e..8d35745d 100644
--- a/.github/workflows/macos.yml
+++ b/.github/workflows/macos.yml
@@ -16,3 +16,9 @@ jobs:
     uses: ./.github/workflows/ci.yml
     with:
       runner: macos-latest
+      test_matrix: >-
+        {
+          "include": [
+            { "mode": "test", "CC": "gcc", "CXX": "g++", "buildtype": "release" }
+          ]
+        }
diff --git a/.github/workflows/minver.yml b/.github/workflows/minver.yml
index 312f43a5..2beabf50 100644
--- a/.github/workflows/minver.yml
+++ b/.github/workflows/minver.yml
@@ -18,3 +18,9 @@ jobs:
       runner: ubuntu-latest
       container: archlinux/archlinux:latest
       verset: minver
+      test_matrix: >-
+        {
+          "include": [
+            { "mode": "test", "CC": "gcc", "CXX": "g++", "buildtype": "release" }
+          ]
+        }

From 5ec066c5899fc74f075cf82a6b3a3a20aee11ef7 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Fri, 16 Feb 2024 11:32:49 -0500
Subject: [PATCH 28/37] fix: remove the test leak

---
 src/iguana/algorithms/clas12/LorentzTransformer.cc | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/iguana/algorithms/clas12/LorentzTransformer.cc b/src/iguana/algorithms/clas12/LorentzTransformer.cc
index bdb17c10..60125388 100644
--- a/src/iguana/algorithms/clas12/LorentzTransformer.cc
+++ b/src/iguana/algorithms/clas12/LorentzTransformer.cc
@@ -26,7 +26,6 @@ namespace iguana::clas12 {
 
 
   void LorentzTransformer::Run(hipo::banklist& banks) const {
-    auto leak = new Object("leak");
     auto& particleBank = GetBank(banks, b_particle, "REC::Particle");
     ShowBank(particleBank, Logger::Header("INPUT PARTICLES"));
     for(int row = 0; row < particleBank.getRows(); row++) {

From f06d249e523566a65dbb40451a0623478652f889 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Fri, 16 Feb 2024 11:41:01 -0500
Subject: [PATCH 29/37] test: PIE build

---
 .github/workflows/ci.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9de16c83..edcdb863 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -82,7 +82,7 @@ jobs:
           ref: ${{ env.hipo_version }}
       - name: build
         run: |
-          cmake -S . -B build -G Ninja --install-prefix $(pwd)/hipo
+          cmake -S . -B build -G Ninja --install-prefix $(pwd)/hipo -DCMAKE_POSITION_INDEPENDENT_CODE=ON
           cmake --build build
           cmake --install build
           tar czvf hipo{.tar.gz,}
@@ -268,6 +268,7 @@ jobs:
               meson configure     \
                 -Db_sanitize=$san \
                 -Db_lundef=false  \
+                -Db_pie=true      \
                 build-iguana
               ;;
           esac

From cf5238e7df673d65472d2d5db48af933e7b58bac Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Fri, 16 Feb 2024 11:54:27 -0500
Subject: [PATCH 30/37] fix: disable MSAN, because of false positives

---
 .github/workflows/ci.yml | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index edcdb863..9709a086 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -21,6 +21,9 @@ on:
         description: 'Test matrix for `test_iguana` job (JSON)'
         required: false
         type: string
+        # test coverage and sanitizers
+        # FIXME: `b_sanitize=memory` is not used because `libc++` needs to be re-compiled with `-fsanitize=memory`, otherwise
+        #        we are bothered by false positives (e.g., from `std::map` insertion)
         default: >-
           {
             "include": [
@@ -28,7 +31,6 @@ on:
               { "mode": "san_address",   "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
               { "mode": "san_thread",    "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
               { "mode": "san_undefined", "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
-              { "mode": "san_memory",    "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
               { "mode": "san_leak",      "CC": "clang", "CXX": "clang++", "buildtype": "debug"   }
             ]
           }
@@ -82,7 +84,7 @@ jobs:
           ref: ${{ env.hipo_version }}
       - name: build
         run: |
-          cmake -S . -B build -G Ninja --install-prefix $(pwd)/hipo -DCMAKE_POSITION_INDEPENDENT_CODE=ON
+          cmake -S . -B build -G Ninja --install-prefix $(pwd)/hipo -DCMAKE_POSITION_INDEPENDENT_CODE=ON # using PIE build, for sanitizer readibility
           cmake --build build
           cmake --install build
           tar czvf hipo{.tar.gz,}

From 04b476f84cd4d0d2fa9775ac083b8d05b46c6a79 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Fri, 16 Feb 2024 12:51:30 -0500
Subject: [PATCH 31/37] refactor: generalize `iguana-test`

---
 src/iguana/tests/iguana-test.cc | 85 ++++++++++++++++++++++++++++-----
 src/iguana/tests/meson.build    | 11 ++++-
 2 files changed, 84 insertions(+), 12 deletions(-)

diff --git a/src/iguana/tests/iguana-test.cc b/src/iguana/tests/iguana-test.cc
index be9f538c..c75da515 100644
--- a/src/iguana/tests/iguana-test.cc
+++ b/src/iguana/tests/iguana-test.cc
@@ -1,22 +1,76 @@
+#include <getopt.h>
 #include <iguana/algorithms/AlgorithmSequence.h>
 #include <hipo4/reader.h>
 
 int main(int argc, char **argv) {
 
   // parse arguments
-  if(argc-1 < 3) {
-    fmt::print(stderr, "USAGE: {} [data_file] [num_events] [algorithm_name] [banks]...\n", argv[0]);
-    return 2;
-  }
-  const std::string data_file  = std::string(argv[1]);
-  const int         num_events = std::stoi(argv[2]);
-  const std::string algo_name  = std::string(argv[3]);
+  int                      opt;
+  std::string              command = "";
+  std::string              data_file = "";
+  int                      num_events = 10;
+  std::string              algo_name = "";
   std::vector<std::string> bank_names;
   bool verbose = false;
-  for(int i=4; i<argc; i++)
-    bank_names.push_back(std::string(argv[i]));
+  auto Usage = [&]() {
+    fmt::print(stderr, "\nUSAGE: {} [OPTIONS]...\n", argv[0]);
+    fmt::print("\n");
+    fmt::print("  OPTIONS:\n");
+    fmt::print("\n");
+    fmt::print("    {:<20} {}\n\n", "-c COMMAND", "which test command to use:");
+    fmt::print("    {:<20} {:<15} {}\n", "", "algorithm", "call `Run` on an algorithm");
+    fmt::print("    {:<20} {:<15} {}\n", "", "unit", "call `Test` on an algorithm, for unit tests");
+    fmt::print("\n");
+    fmt::print("    {:<20} {}\n", "-f FILE", "input data file, for when COMMAND==algorithm");
+    fmt::print("\n");
+    fmt::print("    {:<20} {}\n", "-n NUM_EVENTS", "number of events from the data file");
+    fmt::print("    {:<20} default: {}\n", "", num_events);
+    fmt::print("\n");
+    fmt::print("    {:<20} {}\n", "-a ALGORITHM", "the name of the algorithm");
+    fmt::print("\n");
+    fmt::print("    {:<20} {}\n", "-b BANKS", "add a bank to process");
+    fmt::print("\n");
+    fmt::print("    {:<20} {}\n", "-v", "increase verbosity");
+    fmt::print("\n");
+    return 2;
+  };
+  if(argc==1)
+    return Usage();
+  while((opt=getopt(argc, argv, "c:f:n:a:b:v|")) != -1) {
+    switch(opt) {
+      case 'c':
+        command = std::string(optarg);
+        break;
+      case 'f':
+        data_file = std::string(optarg);
+        break;
+      case 'n':
+        num_events = std::stoi(optarg);
+        break;
+      case 'a':
+        algo_name = std::string(optarg);
+        break;
+      case 'b':
+        bank_names.push_back(std::string(optarg));
+        break;
+      case 'v':
+        verbose = true;
+        break;
+      default:
+        return Usage();
+    }
+  }
+  if(command == "" || algo_name == "" || bank_names.empty()) {
+    fmt::print(stderr, "ERROR: need at least a command, algorithm name, and banks\n");
+    return Usage();
+  }
+  if(command == "algorithm" && data_file == "") {
+    fmt::print(stderr, "ERROR: need a data file for command 'algorithm'\n");
+    return Usage();
+  }
   if(verbose) {
     fmt::print("TEST IGUANA:\n");
+    fmt::print("  {:>20} = {}\n", "command", command);
     fmt::print("  {:>20} = {}\n", "data_file", data_file);
     fmt::print("  {:>20} = {}\n", "num_events", num_events);
     fmt::print("  {:>20} = {}\n", "algo_name", algo_name);
@@ -34,7 +88,7 @@ int main(int argc, char **argv) {
   // define the algorithm
   iguana::AlgorithmSequence seq;
   seq.Add(algo_name);
-  seq.SetOption(algo_name, "log", "debug");
+  seq.SetOption(algo_name, "log", verbose ? "debug" : "info");
 
   // start the algorithm
   seq.Start(banks_after);
@@ -45,7 +99,16 @@ int main(int argc, char **argv) {
     // iterate the 'before' reader too
     reader_before.next(banks_before);
     // run the algorithm
-    seq.Run(banks_after);
+    if(command=="algorithm")
+      seq.Run(banks_after);
+    else if(command=="unit") {
+      fmt::print(stderr, "ERROR: unit tests are not yet implemented (TODO)\n");
+      return 1;
+    }
+    else {
+      fmt::print(stderr, "ERROR: unknown command '{}'\n", command);
+      return 1;
+    }
     // print the banks, before and after
     if(verbose) {
       for(decltype(bank_names)::size_type it_bank=0; it_bank < bank_names.size(); it_bank++) {
diff --git a/src/iguana/tests/meson.build b/src/iguana/tests/meson.build
index afae5ad3..537c7765 100644
--- a/src/iguana/tests/meson.build
+++ b/src/iguana/tests/meson.build
@@ -13,10 +13,19 @@ test_exe = executable(
 if fs.is_file(get_option('test_data_file'))
   message('Test sample file provided; you may run tests with `meson test`')
   foreach algo, banks : algos_and_banks_for_unit_testing
+    bank_args = []
+    foreach bank : banks
+      bank_args += ['-b', bank]
+    endforeach
     test(
       test_exe_name + ' ' + algo.replace('::', '__'),
       test_exe,
-      args: [ get_option('test_data_file'), get_option('test_num_events'), algo ] + banks,
+      args: [
+        '-c', 'algorithm',
+        '-f', get_option('test_data_file'),
+        '-n', get_option('test_num_events'),
+        '-a', algo
+        ] + bank_args,
     )
   endforeach
 else

From f97547d912c5e87dd57193d75343584b29c60b61 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Mon, 19 Feb 2024 15:42:04 -0500
Subject: [PATCH 32/37] fix: centralize executables' rpath

---
 examples/meson.build         | 17 +----------------
 meson.build                  | 15 +++++++++++++++
 src/iguana/tests/meson.build |  2 +-
 3 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/examples/meson.build b/examples/meson.build
index 6fe166d2..6a976fe7 100644
--- a/examples/meson.build
+++ b/examples/meson.build
@@ -5,21 +5,6 @@ example_sources = [
   'iguana-example-03-zvertex-filter.cc',
 ]
 
-# add dependencies' libraries to rpath
-example_rpaths = [
-  hipo_dep.get_variable(pkgconfig: 'libdir'),
-]
-if host_machine.system() != 'darwin'
-  # FIXME(darwin): not sure how to set multiple rpaths on darwin executables, aside
-  # from running `install_name_tool -add_rpath` post-installation; luckily,
-  # darwin-built examples only need `hipo_dep` libraries in the rpath and they
-  # don't need the `iguana` library path explictly included in the rpath, so
-  # this `if` block just keeps `example_rpaths` to only one element. If we need
-  # more rpath elements someday, either we need to use `install_name_tool` or,
-  # preferably, resolution of https://github.com/mesonbuild/meson/issues/5760
-  example_rpaths += '$ORIGIN' / '..' / get_option('libdir')
-endif
-
 # build executables
 foreach src : example_sources
   executable(
@@ -29,7 +14,7 @@ foreach src : example_sources
     dependencies:        project_deps,
     link_with:           project_libs,
     install:             true,
-    install_rpath:       ':'.join(example_rpaths),
+    install_rpath:       ':'.join(project_exe_rpath),
   )
 endforeach
 
diff --git a/meson.build b/meson.build
index 293b1577..2647caf7 100644
--- a/meson.build
+++ b/meson.build
@@ -66,6 +66,21 @@ project_pkg_vars  = [
   'dep_libdirs='       + ':'.join(dep_lib_paths),
 ]
 
+# executables' rpath
+project_exe_rpath = [
+  hipo_dep.get_variable(pkgconfig: 'libdir'),
+]
+if host_machine.system() != 'darwin'
+  # FIXME(darwin): not sure how to set multiple rpaths on darwin executables, aside
+  # from running `install_name_tool -add_rpath` post-installation; luckily,
+  # darwin-built examples only need `hipo_dep` libraries in the rpath and they
+  # don't need the `iguana` library path explictly included in the rpath, so
+  # this `if` block just keeps `project_exe_rpath` to only one element. If we need
+  # more rpath elements someday, either we need to use `install_name_tool` or,
+  # preferably, resolution of https://github.com/mesonbuild/meson/issues/5760
+  project_exe_rpath += '$ORIGIN' / '..' / get_option('libdir')
+endif
+
 # set preprocessor macros
 add_project_arguments(
   '-DIGUANA_ETC="' + get_option('prefix') / project_etc + '"',
diff --git a/src/iguana/tests/meson.build b/src/iguana/tests/meson.build
index 537c7765..b001325e 100644
--- a/src/iguana/tests/meson.build
+++ b/src/iguana/tests/meson.build
@@ -7,7 +7,7 @@ test_exe = executable(
   dependencies:        project_deps,
   link_with:           project_libs,
   install:             true,
-  # install_rpath:     # don't bother with rpath, since `meson test` will run it in the build directory
+  install_rpath:       ':'.join(project_exe_rpath),
 )
 
 if fs.is_file(get_option('test_data_file'))

From b061357887740f202deff76e365b5ea30eaa5897 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Mon, 19 Feb 2024 16:11:23 -0500
Subject: [PATCH 33/37] fix: macos test no longer runs coverage; remove gcovr

---
 .github/install-dependency-packages.sh | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/install-dependency-packages.sh b/.github/install-dependency-packages.sh
index 444b872f..39a776c4 100755
--- a/.github/install-dependency-packages.sh
+++ b/.github/install-dependency-packages.sh
@@ -31,7 +31,6 @@ GENERAL_PACKAGE_LIST_MACOS=(
   tree
   ninja
   meson
-  gcovr
 )
 IGUANA_PACKAGE_LIST_MACOS=(
   fmt

From 266eedb89500061f50bccef2a68fa8f331123780 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Mon, 19 Feb 2024 16:12:01 -0500
Subject: [PATCH 34/37] ci: better sanitizer job names

---
 .github/workflows/ci.yml | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9709a086..3ac0ca93 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -27,11 +27,11 @@ on:
         default: >-
           {
             "include": [
-              { "mode": "coverage",      "CC": "gcc",   "CXX": "g++",     "buildtype": "release" },
-              { "mode": "san_address",   "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
-              { "mode": "san_thread",    "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
-              { "mode": "san_undefined", "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
-              { "mode": "san_leak",      "CC": "clang", "CXX": "clang++", "buildtype": "debug"   }
+              { "mode": "coverage",                     "CC": "gcc",   "CXX": "g++",     "buildtype": "release" },
+              { "mode": "address sanitizer",            "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
+              { "mode": "thread sanitizer",             "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
+              { "mode": "undefined behavior sanitizer", "CC": "clang", "CXX": "clang++", "buildtype": "debug"   },
+              { "mode": "leak sanitizer",               "CC": "clang", "CXX": "clang++", "buildtype": "debug"   }
             ]
           }
 
@@ -265,8 +265,8 @@ jobs:
                 -Db_coverage=true \
                 build-iguana
               ;;
-            san_*)
-              san=$(echo ${{ matrix.mode }} | sed 's;^san_;;')
+            *sanitizer)
+              san=$(echo ${{ matrix.mode }} | sed 's; .*;;g')
               meson configure     \
                 -Db_sanitize=$san \
                 -Db_lundef=false  \

From 45ad26ab799009362c809ee990adf342590c9ae7 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Mon, 19 Feb 2024 16:24:12 -0500
Subject: [PATCH 35/37] fix: quotes

---
 .github/workflows/ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3ac0ca93..e8912a95 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -259,7 +259,7 @@ jobs:
             -Dtest_data_file=$(pwd)/test_data.hipo \
             -Dtest_num_events=1000                 \
             build-iguana
-          case ${{ matrix.mode }} in
+          case "${{ matrix.mode }}" in
             coverage)
               meson configure     \
                 -Db_coverage=true \

From 550e9a0cd687526a1d81f18c1a263f21f1dd4737 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Mon, 19 Feb 2024 16:41:04 -0500
Subject: [PATCH 36/37] fix: deploy pages only on `main`

---
 .github/workflows/ci.yml | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e8912a95..fbd0ccd1 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -473,8 +473,7 @@ jobs:
   #########################################################
 
   collect_webpages:
-    # if: ${{ (github.head_ref == 'main' || github.ref_name == 'main') && inputs.runner == 'ubuntu-latest' && inputs.verset == 'latest' }}
-    if: ${{ (github.head_ref == 'meson-test' || github.ref_name == 'meson-test') && inputs.runner == 'ubuntu-latest' && inputs.verset == 'latest' }}
+    if: ${{ (github.head_ref == 'main' || github.ref_name == 'main') && inputs.runner == 'ubuntu-latest' && inputs.verset == 'latest' }}
     name: Collect webpages
     needs:
       - doc_generate
@@ -508,8 +507,7 @@ jobs:
           path: pages/
 
   deploy_webpages:
-    # if: ${{ (github.head_ref == 'main' || github.ref_name == 'main') && inputs.runner == 'ubuntu-latest' && inputs.verset == 'latest' }}
-    if: ${{ (github.head_ref == 'meson-test' || github.ref_name == 'meson-test') && inputs.runner == 'ubuntu-latest' && inputs.verset == 'latest' }}
+    if: ${{ (github.head_ref == 'main' || github.ref_name == 'main') && inputs.runner == 'ubuntu-latest' && inputs.verset == 'latest' }}
     name: Deploy webpages
     needs: collect_webpages
     permissions:

From aa2f544c02000395d2c31d18874db511c908bd44 Mon Sep 17 00:00:00 2001
From: Christopher Dilks <c-dilks@users.noreply.github.com>
Date: Mon, 19 Feb 2024 17:13:57 -0500
Subject: [PATCH 37/37] ci: drop redundant matrix specs

---
 .github/workflows/ci.yml | 13 ++-----------
 1 file changed, 2 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index fbd0ccd1..ec1a2a58 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -107,19 +107,13 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        id:
-          # build C++-only version with various compilers and buildtypes
-          - cpp-gcc-release
-          - cpp-gcc-debug
-          - cpp-clang-release
-          - cpp-clang-debug
-          # build with bindings
-          - python
         include:
+          # build C++-only version with various compilers and buildtypes
           - { id: cpp-gcc-release,   CC: gcc,   CXX: g++,     buildtype: release, binding_opts: ''                   }
           - { id: cpp-gcc-debug,     CC: gcc,   CXX: g++,     buildtype: debug,   binding_opts: ''                   }
           - { id: cpp-clang-release, CC: clang, CXX: clang++, buildtype: release, binding_opts: ''                   }
           - { id: cpp-clang-debug,   CC: clang, CXX: clang++, buildtype: debug,   binding_opts: ''                   }
+          # build with bindings
           - { id: python,            CC: gcc,   CXX: g++,     buildtype: release, binding_opts: '-Dbind_python=True' }
     env:
       CC: ${{ matrix.CC }}
@@ -323,9 +317,6 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        id:
-          - cpp-gcc-release
-          - python
         include:
           - { id: cpp-gcc-release, extension: ''    }
           - { id: python,          extension: '.py' }