Include compiled mod files. (#1131)

Add a script for generating the reference values of compiled mod files.
These are included with the sources to enable the following:

  * during review the reviewer can see what was generated.
  * these can serve as golden tests, flagging changes in unrelated mod
    files.

---------

Co-authored-by: JCGoran <[email protected]>

.bbp-project.yaml

@@ -5,6 +5,7 @@ tools:
       match:
       - ext/.*
       - src/language/templates/*
+      - test/usecases/*/*
   ClangTidy:
     enable: true
     option: ''

.gitmodules

@@ -25,3 +25,6 @@
 [submodule "ext/backward"]
 	path = ext/backward
 	url = https://github.com/bombela/backward-cpp.git
+[submodule "test/usecases/references"]
+	path = test/usecases/references
+	url = https://github.com/BlueBrain/nmodl-references.git

CONTRIBUTING.rst

@@ -165,6 +165,33 @@ The HPC coding conventions formatter installs any dependencies into a Python
 virtual environment.
 
 
+Updating Golden References
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Run
+
+.. code:: bash
+
+   cmake --build <build-dir> --target generate_references
+
+to regenerate the golden references. They are saved in a submodule
+``tests/usecases/references``, which points to ``BlueBrain/nmodl-references``.
+
+Create a PR for the changes to the references and update the SHA in the NMODL
+repo. It might be useful to change to SSH authentication:
+
+.. code:: bash
+
+   git remote set-url origin ssh://[email protected]/BlueBrain/nmodl-references
+
+(from inside ``tests/usecases/references``).
+
+Remember the rules of submodules: They're checked out on a specific commit,
+i.e. detached HEAD. If you want to modify the submodule, it's usual best to
+checkout ``main`` from then on the submodule will behave much like a Git repo
+that happens to be located inside a Git repo.
+
+
 Validate the Python package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

test/usecases/CMakeLists.txt

@@ -7,8 +7,37 @@ set(NMODL_USECASE_DIRS
     func_proc
     func_proc_pnt)
 
+file(GLOB NMODL_GOLDEN_REFERENCES "${CMAKE_CURRENT_SOURCE_DIR}/references/*")
+if(NMODL_GOLDEN_REFERENCES STREQUAL "")
+  cpp_cc_init_git_submodule(${CMAKE_CURRENT_SOURCE_DIR}/references)
+endif()
+unset(NMODL_GOLDEN_REFERNCES)
+
+add_custom_target(generate_references)
 foreach(usecase ${NMODL_USECASE_DIRS})
+  # Non-existant dependencies are a way of unconditionally running commands in CMake.
+  if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/references/${usecase}/_does_not_exist_weiohbge)
+    message(
+      FATAL_ERROR
+        "The file: '${CMAKE_CURRENT_SOURCE_DIR}/references/${usecase}/_does_not_exist_weiohbge' must not exist."
+    )
+  endif()
+
   add_test(NAME usecase_${usecase}
            COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/run_test.sh ${CMAKE_BINARY_DIR}/bin/nmodl
                    ${CMAKE_CURRENT_SOURCE_DIR}/${usecase})
+
+  add_test(NAME golden_${usecase}
+           COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/check_references.sh ${CMAKE_BINARY_DIR}/bin/nmodl
+                   ${CMAKE_CURRENT_SOURCE_DIR}/${usecase})
+
+  add_custom_command(
+    OUTPUT ${CMAKE_CURRENT_SOURCE_DIR}/references/${usecase}/_does_not_exist_weiohbge
+    COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/generate_references.sh ${CMAKE_BINARY_DIR}/bin/nmodl
+            ${CMAKE_CURRENT_SOURCE_DIR}/${usecase})
+
+  add_custom_target(
+    generate_${usecase}
+    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/references/${usecase}/_does_not_exist_weiohbge)
+  add_dependencies(generate_references generate_${usecase})
 endforeach()

test/usecases/check_references.sh

@@ -0,0 +1,18 @@
+#! /usr/bin/env bash
+set -u
+
+script_dir="$(dirname "$(realpath "$0")")"
+nmodl="$1"
+usecase_dir="$2"
+references_dir="${script_dir}/references/$(basename "$2")"
+output_dir="$(mktemp -d)"
+
+"${script_dir}"/generate_references.sh ${nmodl} "${usecase_dir}" "${output_dir}"
+
+diff -U 8 -r "${references_dir}" "${output_dir}"
+
+exit_code=$?
+
+rm -r "${output_dir}"
+
+exit $exit_code

test/usecases/generate_references.sh

@@ -0,0 +1,33 @@
+#! /usr/bin/env bash
+set -eu
+
+nmodl="$1"
+usecase_dir="$2"
+
+if [[ $# -eq 3 ]]
+then
+  output_dir="$3"
+else
+  script_dir="$(dirname "$(realpath "$0")")"
+  output_dir="${script_dir}/references/$(basename "$2")"
+fi
+
+function sanitize() {
+  for f in "${1}"/*.cpp
+  do
+    if [[ "$(uname)" == 'Darwin' ]]
+    then
+        sed_cmd="sed -i''"
+    else
+        sed_cmd="sed -i"
+    fi
+    ${sed_cmd} "s/Created         : .*$/Created         : DATE/" "$f"
+    ${sed_cmd} "s/NMODL Compiler  : .*$/NMODL Compiler  : VERSION/" "$f"
+  done
+}
+
+"${nmodl}" "${usecase_dir}"/*.mod --neuron -o "${output_dir}/neuron"
+sanitize "${output_dir}/neuron"
+
+"${nmodl}" "${usecase_dir}"/*.mod -o "${output_dir}"/coreneuron
+sanitize "${output_dir}/coreneuron"

test/usecases/run_test.sh

@@ -1,5 +1,10 @@
 #! /usr/bin/env bash
-set -e
+set -eu
+
+if [[ $# -ne 2 ]]
+then
+  echo "Usage: $0 NMODL USECASE_DIR"
+fi
 
 nmodl="$1"
 output_dir="$(uname -m)"