feat: chameleon, a tool for language binding generation

.github/workflows/ci.yml

@@ -234,6 +234,14 @@ jobs:
           source .venv/bin/activate
           echo PATH=$PATH >> $GITHUB_ENV
           python -m pip install -r iguana_src/bind/python/requirements.txt
+      ###### install doxygen
+      - name: install doxygen
+        if: ${{ matrix.id == 'documentation' }}
+        run: |
+          pacman -S --noconfirm doxygen graphviz
+          echo "INSTALLED VERSIONS:"
+          echo "doxygen: $(doxygen --version)"
+          echo "$(dot --version)"
       ###### hipo
       - name: get `hipo-withROOT` build
         if: ${{ matrix.id != 'noROOT' }}
@@ -275,11 +283,6 @@ jobs:
       ### build
       - name: meson setup
         run: |
-          if [ "${{ matrix.id }}" = "cpp" ]; then
-            validate_all="true" # 'cpp' job will upload validator artifacts, so use all statistics
-          else
-            validate_all="false"
-          fi
           meson setup iguana_build iguana_src           \
             --prefix=$(pwd)/iguana                      \
             --pkg-config-path=$(pwd)/hipo/lib/pkgconfig \
@@ -288,7 +291,6 @@ jobs:
             -Dtest_data_file=$(pwd)/test_data.hipo      \
             -Dtest_num_events=${{ env.num_events }}     \
             -Dtest_output_dir=$(pwd)/validation_results \
-            -Dtest_validator_all_stats=${validate_all}  \
             ${{ matrix.opts }}
       - name: dump build options
         run: meson configure iguana_build --no-pager
@@ -398,47 +400,34 @@ jobs:
           echo "========================================= TEST RUN ========================================="
           install_consumer_cmake/bin/iguana_ex_cpp_00_run_functions test_data.hipo 10
       ### upload artifacts
-      - uses: actions/upload-artifact@v4
+      - name: upload build log artifacts
+        uses: actions/upload-artifact@v4
         if: always()
         with:
           name: logs_iguana_build_${{ matrix.id }}
           retention-days: 5
           path: iguana_build/meson-logs
-      - uses: actions/upload-artifact@v4
+      - name: upload coverage artifacts
+        uses: actions/upload-artifact@v4
         if: ${{ matrix.id == 'coverage' }}
         with:
           name: coverage-report
           retention-days: 5
           path: coverage-report
-      - uses: actions/upload-artifact@v4
+      - name: upload validator artifacts
+        uses: actions/upload-artifact@v4
         if: ${{ matrix.id == 'cpp' }}
         with:
           name: _validation_results
           retention-days: 5
           path: validation_results
-
-  # documentation
-  #########################################################
-
-  doc_generate:
-    if: ${{ inputs.id == 'linux-latest' }}
-    name: Generate documentation
-    runs-on: ${{ inputs.runner }}
-    container:
-      image: ${{ inputs.container }}
-    steps:
-      - uses: actions/checkout@v4
-      - name: install dependencies
-        run: |
-          pacman -Syu --noconfirm
-          pacman -S --noconfirm doxygen graphviz
-      - name: doxygen
-        run: doxygen doc/gen/Doxyfile
-      - uses: actions/upload-artifact@v4
+      - name: upload documentation artifacts
+        uses: actions/upload-artifact@v4
+        if: ${{ matrix.id == 'documentation' }}
         with:
           name: doc_doxygen
           retention-days: 5
-          path: doc/api/
+          path: iguana/share/doc/iguana/html/
 
   # deployment
   #########################################################
@@ -447,7 +436,6 @@ jobs:
     if: ${{ github.ref == 'refs/heads/main' && inputs.id == 'linux-latest' }}
     name: Collect webpages
     needs:
-      - doc_generate
       - iguana
     runs-on: ${{ inputs.runner }}
     steps:

.github/workflows/linux.yml

@@ -24,6 +24,7 @@ jobs:
           "id": [
             "cpp",
             "coverage",
+            "documentation",
             "address-sanitizer",
             "thread-sanitizer",
             "undefined-sanitizer",
@@ -33,8 +34,9 @@ jobs:
             "fortran"
           ],
           "include": [
-            { "id": "cpp",                 "CC": "gcc",   "CXX": "g++",     "opts": "-Dbuildtype=release -Dz_require_root=true"  },
+            { "id": "cpp",                 "CC": "gcc",   "CXX": "g++",     "opts": "-Dbuildtype=release -Dz_require_root=true   -Dtest_validator_all_stats=true"  },
             { "id": "coverage",            "CC": "gcc",   "CXX": "g++",     "opts": "-Dbuildtype=release -Dz_require_root=true   -Db_coverage=true"     },
+            { "id": "documentation",       "CC": "gcc",   "CXX": "g++",     "opts": "-Dbuildtype=release -Dz_require_root=true   -Dinstall_documentation=true" },
             { "id": "address-sanitizer",   "CC": "clang", "CXX": "clang++", "opts": "-Dbuildtype=debug   -Dz_require_root=true   -Db_sanitize=address   -Db_lundef=false -Db_pie=true" },
             { "id": "thread-sanitizer",    "CC": "clang", "CXX": "clang++", "opts": "-Dbuildtype=debug   -Dz_require_root=true   -Db_sanitize=thread    -Db_lundef=false -Db_pie=true" },
             { "id": "undefined-sanitizer", "CC": "clang", "CXX": "clang++", "opts": "-Dbuildtype=debug   -Dz_require_root=true   -Db_sanitize=undefined -Db_lundef=false -Db_pie=true" },

.github/workflows/macos.yml

@@ -25,7 +25,7 @@ jobs:
             "fortran"
           ],
           "include": [
-            { "id": "cpp",     "CC": "gcc", "CXX": "g++", "opts": "-Dbuildtype=release -Dz_require_root=true"  },
+            { "id": "cpp",     "CC": "gcc", "CXX": "g++", "opts": "-Dbuildtype=release -Dz_require_root=true   -Dtest_validator_all_stats=true"  },
             { "id": "noROOT",  "CC": "gcc", "CXX": "g++", "opts": "-Dbuildtype=release -Dz_require_root=false" },
             { "id": "python",  "CC": "gcc", "CXX": "g++", "opts": "-Dbuildtype=release -Dz_require_root=true   -Dbind_python=true"  },
             { "id": "fortran", "CC": "gcc", "CXX": "g++", "opts": "-Dbuildtype=release -Dz_require_root=true   -Dbind_fortran=true" }

.github/workflows/minver.yml

@@ -27,7 +27,7 @@ jobs:
             "fortran"
           ],
           "include": [
-            { "id": "cpp",     "CC": "gcc", "CXX": "g++", "opts": "-Dbuildtype=release -Dz_require_root=true"  },
+            { "id": "cpp",     "CC": "gcc", "CXX": "g++", "opts": "-Dbuildtype=release -Dz_require_root=true   -Dtest_validator_all_stats=true"  },
             { "id": "noROOT",  "CC": "gcc", "CXX": "g++", "opts": "-Dbuildtype=release -Dz_require_root=false" },
             { "id": "python",  "CC": "gcc", "CXX": "g++", "opts": "-Dbuildtype=release -Dz_require_root=true   -Dbind_python=true"  },
             { "id": "fortran", "CC": "gcc", "CXX": "g++", "opts": "-Dbuildtype=release -Dz_require_root=true   -Dbind_fortran=true" }

.gitignore

@@ -10,8 +10,8 @@
 /share
 /.cache
 
-# documentation artifacts
-/doc/api
+# chameleon artifacts
+chameleon-tree
 
 # data files
 *.hipo

bind/python/iguana_ex_python_01_action_functions.py

@@ -54,7 +54,7 @@
                        # it requires reading full `hipo::bank` objects, whereas this example is meant to demonstrate
                        # `iguana` usage operating _only_ on bank row elements
 
-            px, py, pz, = algo_momentum_correction.Transform(
+            p_corrected = algo_momentum_correction.Transform(
                     particleBank.getFloat("px", row),
                     particleBank.getFloat("py", row),
                     particleBank.getFloat("pz", row),
@@ -65,7 +65,7 @@
 
             print(f'Accepted PID {pid}:')
             print(f'  p_old = ({particleBank.getFloat("px", row)}, {particleBank.getFloat("py", row)}, {particleBank.getFloat("pz", row)})')
-            print(f'  p_new = ({px}, {py}, {pz})')
+            print(f'  p_new = ({p_corrected.px}, {p_corrected.py}, {p_corrected.pz})')
 
 algo_eventbuilder_filter.Stop()
 algo_momentum_correction.Stop()

bind/python/iguana_ex_python_hipopy.py

@@ -55,7 +55,7 @@
                         # it requires reading full `hipo::bank` objects, whereas this example is meant to demonstrate
                         # `iguana` usage operating _only_ on bank row elements
 
-                px, py, pz, = algo_momentum_correction.Transform(
+                p_corrected = algo_momentum_correction.Transform(
                     batch['REC::Particle_px'][iEvent][row],
                     batch['REC::Particle_py'][iEvent][row],
                     batch['REC::Particle_pz'][iEvent][row],
@@ -66,7 +66,7 @@
 
                 print(f'Accepted PID {pid}:')
                 print(f'  p_old = ({batch["REC::Particle_px"][iEvent][row]}, {batch["REC::Particle_py"][iEvent][row]}, {batch["REC::Particle_pz"][iEvent][row]})')
-                print(f'  p_new = ({px}, {py}, {pz})')
+                print(f'  p_new = ({p_corrected.px}, {p_corrected.py}, {p_corrected.pz})')
 
     # End iteration if maximum number of batches reached
     if (iBatch>=nbatches): break

bind/python/meson.build

@@ -1,3 +1,4 @@
+pythondir = 'python'
 project_pkg_vars += 'pythonpath=' + '${prefix}' / pythondir
 
 install_subdir('pyiguana', install_dir: pythondir)

doc/gen/Doxyfile → doc/gen/Doxyfile.in

@@ -48,7 +48,7 @@ PROJECT_NAME           = "Iguana"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         =
+PROJECT_NUMBER         = @version@
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -68,7 +68,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       =
+OUTPUT_DIRECTORY       = @top_builddir@/doc/gen
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096
 # sub-directories (in 2 levels) under the output directory of each output format
@@ -832,7 +832,7 @@ FILE_VERSION_FILTER    =
 # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
 # tag is left empty.
 
-LAYOUT_FILE            = doc/gen/DoxygenLayout.xml
+LAYOUT_FILE            = @top_srcdir@/doc/gen/DoxygenLayout.xml
 
 # The CITE_BIB_FILES tag can be used to specify one or more bib files containing
 # the reference definitions. This must be a list of .bib files. The .bib
@@ -853,7 +853,7 @@ CITE_BIB_FILES         =
 # messages are off.
 # The default value is: NO.
 
-QUIET                  = NO
+QUIET                  = YES
 
 # The WARNINGS tag can be used to turn on/off the warning messages that are
 # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES
@@ -960,11 +960,12 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = src/ \
-                         bind/ \
-                         doc/gen/ \
-                         doc/gen/mainpage.md \
-                         examples/
+INPUT                  = @top_srcdir@/src/ \
+                         @top_builddir@/src/iguana/algorithms \
+                         @top_srcdir@/bind/ \
+                         @top_srcdir@/doc/gen/ \
+                         @top_srcdir@/doc/gen/mainpage.md \
+                         @top_srcdir@/examples/
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1006,9 +1007,9 @@ INPUT_FILE_ENCODING    =
 
 FILE_PATTERNS          = *.dox \
                          *.h \
+                         chameleon_*_bind.cc \
                          iguana_ex_*.cc \
                          iguana_ex_*.py \
-                         Bindings.cc \
                          *.f \
                          *.C
 
@@ -1025,8 +1026,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = src/iguana/algorithms/Bindings.cc \
-                         src/iguana/algorithms/clas12/FiducialFilter/Pass1CutData.h
+EXCLUDE                = @top_srcdir@/src/iguana/algorithms/clas12/FiducialFilter/Pass1CutData.h
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -1137,7 +1137,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = doc/gen/mainpage.md
+USE_MDFILE_AS_MAINPAGE = @top_srcdir@/doc/gen/mainpage.md
 
 # The Fortran standard specifies that for fixed formatted Fortran code all
 # characters from position 72 are to be considered as comment. A common
@@ -1269,7 +1269,7 @@ GENERATE_HTML          = YES
 # The default directory is: html.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_OUTPUT            = doc/api
+HTML_OUTPUT            = html
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
 # generated HTML page (for example: .htm, .php, .asp).
@@ -2453,7 +2453,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # set to NO
 # The default value is: NO.
 
-HAVE_DOT               = YES
+HAVE_DOT               = @have_dot@
 
 # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed
 # to run in parallel. When set to 0 doxygen will base this on the number of

doc/gen/fortran.dox

@@ -20,8 +20,8 @@ Iguana provides a set of C functions which are callable from Fortran:
   - `[in,out]`: both an input and an output parameter, will be mutated
 
 @par
-The available C functions and their documentation, organized by C++ namespace, are listed below
-in the **Namespaces** section.
+The available C functions and their documentation, organized by C++ namespace, are listed
+at **the bottom of this page** in the **Namespaces** section.
 
 @par
 For information about each algorithm and their action functions, see:

doc/gen/mainpage.md

@@ -1,9 +1,3 @@
-<!--
-This file is used as a mainpage for the API documentation,
-which is generated by `doxygen`. To generate API
-documentation locally, run `doxygen doc/gen/Doxyfile`
--->
-
 # Iguana User's Guide
 
 This documentation shows how to use the Iguana algorithms.
@@ -18,6 +12,11 @@ To see Iguana algorithms used in the context of analysis code, with **various la
 
 **NOTE:** If you're not familiar with Iguana, please read the sections below first.
 
+## Language Bindings
+
+Iguana algorithms are in C++; to use Iguana with other languages, see:
+- \ref fortran_usage_guide
+
 ## Algorithms
 
 An Iguana algorithm is a function that maps input HIPO bank data to output data. The available algorithms are:

doc/gen/meson.build

@@ -0,0 +1,25 @@
+prog_doxygen = find_program('doxygen')
+prog_dot = find_program('dot', required: false)
+
+doxyfile = configure_file(
+  input: 'Doxyfile.in',
+  output: 'Doxyfile',
+  install: false,
+  configuration: {
+    'version': meson.project_version(),
+    'have_dot': prog_dot.found() ? 'YES' : 'NO',
+    'top_srcdir': meson.project_source_root(),
+    'top_builddir': meson.project_build_root(),
+  },
+)
+
+doc_tgt = custom_target(
+  'documentation',
+  input: doxyfile,
+  output: 'html',
+  build_always_stale: true,
+  build_by_default: true,
+  command: [ prog_doxygen, doxyfile ],
+  install: true,
+  install_dir: join_paths(get_option('datadir'), 'doc', meson.project_name()),
+)

doc/troubleshooting.md

@@ -28,3 +28,13 @@ Then rebuild (`meson compile` and/or `meson install`).
 
 Remember to revert this change and rebuild/re-install, so that Iguana runs with
 full optimization when you are processing large data sets (`-Dbuildtype=release`).
+
+### 🔵 I got some error about "chameleon", or an error in some "chameleon" file that I can't find
+
+[Chameleon is a code generator](/src/chameleon) to automatically create
+`iguana` bindings for programming languages other than C++. All generated code
+is produced in your build directory. If you have issues with Chameleon, either:
+- an `Action.yaml` file is not correct
+- something is wrong with `chameleon`
+
+In either case, open an issue or contact the maintainers.

examples/iguana_ex_fortran_01_action_functions.f

@@ -219,7 +219,8 @@ program iguana_ex_fortran_01_action_functions
               call iguana_clas12_momentumcorrection_transform(
      &          algo_mom_cor,
      &          px(i), py(i), pz(i),
-     &          sector(i), pid(i), torus(1))
+     &          sector(i), pid(i), torus(1),
+     &          px(i), py(i), pz(i))
               print *, '   after: p = (', px(i), py(i), pz(i), ')'
             endif
           enddo