SCIInstitute · dcwhite · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026
diff --git a/.github/superbuild-caching.md b/.github/superbuild-caching.md
@@ -0,0 +1,85 @@
+# Superbuild External Caching
+
+CI caches the compiled external libraries so that builds after the first only need to compile SCIRun itself — not Boost, Qt, Zlib, Python, and ~15 other dependencies from source.
+
+## How it works
+
+SCIRun uses a CMake [Superbuild](../Superbuild/): the outer CMake project drives `ExternalProject_Add` for each dependency, then builds SCIRun itself as the final step. Each external has a series of steps (download → update → configure → build → install), and CMake records completion in stamp files under `Externals/Stamp/`.
+
+### What gets cached
+
+The `actions/cache` step saves and restores two directories:
+
+| Directory | Contents |
+|-----------|----------|
+| `bin/Externals/Install/` | Headers, compiled libs, and cmake config files for every external |
+| `bin/Externals/Stamp/` | CMake stamp files that tell `make` which ExternalProject steps are done |
+
+The cache key is `superbuild-v3-<OS>-<hash of Superbuild/*.cmake>-<variant>-py<bool>`. If any Superbuild cmake file changes, the hash changes and the cache is bypassed entirely — the next build is a full cold build that repopulates the cache.
+
+### Why stamp-touching is needed
+
+CMake rewrites the helper scripts in `Externals/tmp/` (e.g. `Zlib_external-cfgcmd.cmake`) on every configure run, giving them the current timestamp. The Makefile rules for ExternalProject steps depend on those scripts, so restored stamp files (which carry an older timestamp) always appear stale, causing `make` to try re-running every step against source directories that don't exist.
+
+The fix is in `build.sh` (and an equivalent block in the Windows workflow): set the modification time of every file in `Externals/Stamp/` to the year **2100**, immediately after `cmake` configure but before `make`.
+
+A plain `touch` (current time) is not sufficient. CMake's `ExternalProject_Add_Step` generates `add_custom_command` calls whose `DEPENDS` list includes the `ExternalProject.cmake` module file itself. If the GitHub Actions runner has a newer cmake installation than the runner that created the cached stamps, `ExternalProject.cmake` carries a newer timestamp and make considers every step stale regardless of touching. Setting stamps to 2100 makes them unconditionally newer than any cmake module file on any runner.
+
+### Why `UPDATE_COMMAND ""`
+
+By default, `ExternalProject_Add` with `GIT_REPOSITORY` generates a `*-gitupdate.cmake` script that fetches the remote and compares the HEAD hash to `GIT_TAG` on every build. With a restored stamp, this script would still run (for the same timestamp reason above), fail with `fatal: not a git repository` because `Source/` isn't cached, and abort the build.
+
+Setting `UPDATE_COMMAND ""` in every git-based external tells CMake to generate a no-op update step instead — no `gitupdate.cmake` is written, no git operations are needed.
+
+### Why `EP_UPDATE_DISCONNECTED TRUE`
+
+Set globally in `Superbuild.cmake` as an extra safeguard. If for any reason an update stamp is missing (e.g. partial cache), CMake will run the (now no-op) update step once rather than triggering a network fetch.
+
+### Cache key variants
+
+Each OS × build variant × python flag gets its own cache entry. The restore-key is deliberately limited to same-variant matches (`-<variant>-` prefix but no python suffix) so that a `headless` cache is never used to satisfy a `gui` build — they compile different externals.
+
+---
+
+## When an external changes
+
+### Bumping a `GIT_TAG`
+
+Edit the relevant file in `Superbuild/` (e.g. `Superbuild/ZlibExternal.cmake`) and change `GIT_TAG`. Because the cache key hashes all `Superbuild/*.cmake` files, the existing cache is automatically invalidated. The next CI run does a full cold build (~1-2 hours) and saves a fresh cache.
+
+**You do not need to bump the cache version number.**
+
+### Adding a new external
+
+1. Create `Superbuild/MyLibExternal.cmake` following the pattern of an existing file.
+2. Add `UPDATE_COMMAND ""` alongside `GIT_TAG` (or after `URL` for tarball-based externals that don't need it).
+3. Wire it into `Superbuild/Superbuild.cmake`.
+
+The cache key hash will change automatically. Cold build on next CI run, new cache saved.
+
+### Removing an external
+
+Delete the cmake file and remove it from `Superbuild.cmake`. Cache key changes; next run is cold.
+
+### Changing configure or build flags for an external
+
+Edit the relevant `Superbuild/*.cmake` file. Cache key changes; next run is cold.
+
+### Manually busting the cache
+
+If the cache is known-bad (e.g. a broken partial save got promoted), bump the version prefix in `reusable-build.yml`:
+
+```yaml
+key: superbuild-v3-...   →   key: superbuild-v4-...
+```
+
+Update the `restore-keys` lines to match. On the next run every platform does a cold build and the old cache entries age out naturally (GitHub Actions evicts caches after 7 days of disuse).
+
+### Local development note
+
+The `touch Externals/Stamp/` step in `build.sh` runs on local builds too. If you change a `GIT_TAG` locally without clearing your build directory, `make` will skip the download/configure/build steps for that external and use the old installed version. The safest workflow when updating an external locally is:
+
+```sh
+rm -rf bin/Externals
+./build.sh
+```
diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
@@ -53,6 +53,9 @@ on:
 jobs:
   build:
     runs-on: ${{ inputs.runner }}
+    permissions:
+      checks: write
+      contents: read
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -70,6 +73,9 @@ jobs:
       - name: Print Qt dir
         run: echo "QT_ROOT_DIR=${QT_ROOT_DIR:-(unset)}"
 
+      - name: Set up sccache
+        uses: mozilla-actions/sccache-action@v0.0.9
+
       - name: Checkout SCIRunTestData
         if: ${{ inputs.run-regression-tests || inputs.coverage }}
         uses: actions/checkout@v6
@@ -89,6 +95,8 @@ jobs:
         run: |
           set -eux
           CMD=(./build.sh)
+          CMD+=("-DCMAKE_C_COMPILER_LAUNCHER=sccache")
+          CMD+=("-DCMAKE_CXX_COMPILER_LAUNCHER=sccache")
           # Variant-specific flags
           if [ "${{ inputs.variant }}" = "gui" ]; then
             # Pass Qt path (from installer or explicit), and set SCIRUN_QT_MIN_VERSION appropriately
@@ -154,6 +162,8 @@ jobs:
 
           # Build arguments for cmake
           $cmakeArgs = @()
+          $cmakeArgs += "-DCMAKE_C_COMPILER_LAUNCHER=sccache"
+          $cmakeArgs += "-DCMAKE_CXX_COMPILER_LAUNCHER=sccache"
 
           # Always use Visual Studio generator on Windows to ensure MSVC flags are used
           $cmakeArgs += '-G'
@@ -250,7 +260,8 @@ jobs:
         if: ${{ inputs.run-unit-tests && runner.os != 'Windows' }}
         working-directory: bin/SCIRun
         run: |
-          ctest --output-on-failure -j4 -E "\.Test\.ExampleNetwork\." \
+          ctest --output-on-failure --timeout 300 -j4 -E "\.Test\.ExampleNetwork\." \
+            --output-junit "$GITHUB_WORKSPACE/junit-unit.xml" \
             2>&1 | tee /tmp/unit-test-results.txt
         continue-on-error: true
 
@@ -259,6 +270,7 @@ jobs:
         working-directory: bin/SCIRun
         run: |
           ctest --output-on-failure --timeout 300 -j3 -R "\.Test\.ExampleNetwork\." \
+            --output-junit "$GITHUB_WORKSPACE/junit-regression.xml" \
             2>&1 | tee /tmp/regression-test-results.txt
         continue-on-error: true
 
@@ -276,7 +288,8 @@ jobs:
         working-directory: build/SCIRun
         shell: pwsh
         run: |
-          ctest --output-on-failure -j4 -C Release -E "\.Test\.ExampleNetwork\." `
+          ctest --output-on-failure --timeout 300 -j4 -C Release -E "\.Test\.ExampleNetwork\." `
+            --output-junit "$env:GITHUB_WORKSPACE\junit-unit.xml" `
             2>&1 | Tee-Object -FilePath "$env:GITHUB_WORKSPACE\unit-test-results.txt"
         continue-on-error: true
 
@@ -286,9 +299,28 @@ jobs:
         shell: pwsh
         run: |
           ctest --output-on-failure --timeout 300 -j3 -C Release -R "\.Test\.ExampleNetwork\." `
+            --output-junit "$env:GITHUB_WORKSPACE\junit-regression.xml" `
             2>&1 | Tee-Object -FilePath "$env:GITHUB_WORKSPACE\regression-test-results.txt"
         continue-on-error: true
 
+      - name: Publish unit test results
+        uses: dorny/test-reporter@v1
+        if: always() && inputs.run-unit-tests
+        with:
+          name: "Unit Tests (${{ runner.os }} / ${{ inputs.variant }})"
+          path: junit-unit.xml
+          reporter: java-junit
+          fail-on-error: false
+
+      - name: Publish regression test results
+        uses: dorny/test-reporter@v1
+        if: always() && inputs.run-regression-tests
+        with:
+          name: "Regression Tests (${{ runner.os }} / ${{ inputs.variant }})"
+          path: junit-regression.xml
+          reporter: java-junit
+          fail-on-error: false
+
       - name: Upload test logs (Unix)
         if: ${{ (inputs.run-unit-tests || inputs.run-regression-tests) && runner.os != 'Windows' }}
         uses: actions/upload-artifact@v6
@@ -299,6 +331,8 @@ jobs:
             /tmp/unit-test-results.txt
             /tmp/regression-test-results.txt
             bin/SCIRun/Testing/Temporary/LastTest.log
+            junit-unit.xml
+            junit-regression.xml
 
       - name: Upload test logs (Windows)
         if: ${{ (inputs.run-unit-tests || inputs.run-regression-tests) && runner.os == 'Windows' }}
@@ -310,6 +344,8 @@ jobs:
             unit-test-results.txt
             regression-test-results.txt
             build/SCIRun/Testing/Temporary/LastTest.log
+            junit-unit.xml
+            junit-regression.xml
 
       - name: Run tests + coverage report (macOS)
         if: ${{ inputs.coverage && runner.os == 'macOS' }}
@@ -343,3 +379,4 @@ jobs:
             bin/SCIRun/SCIRun-*-Darwin.pkg
             bin/SCIRun/SCIRun-*-win64.exe
             build/**/*.msi
+
diff --git a/Superbuild/Cleaver2External.cmake b/Superbuild/Cleaver2External.cmake
@@ -32,6 +32,7 @@ SET(cleaver2_GIT_TAG "origin/scirun-5.0.0-beta")
 ExternalProject_Add(Cleaver2_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/Cleaver2Library.git"
   GIT_TAG ${cleaver2_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""

diff --git a/Superbuild/CtkExternal.cmake b/Superbuild/CtkExternal.cmake
@@ -45,6 +45,7 @@ LIST(APPEND CTK_CACHE_ARGS
 ExternalProject_Add(Ctk_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/CTK.git"
   GIT_TAG ${ctk_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""

diff --git a/Superbuild/DataExternal.cmake b/Superbuild/DataExternal.cmake
@@ -37,6 +37,7 @@ SET(data_DIR "${SEG3D_BINARY_DIR}/Seg3DData")
 ExternalProject_Add(Data_external
   GIT_REPOSITORY ${data_GIT_URL}
   GIT_TAG ${data_GIT_TAG}
+  UPDATE_COMMAND ""
   SOURCE_DIR ${data_DIR}
   BUILD_COMMAND ""
   CONFIGURE_COMMAND ""

diff --git a/Superbuild/FreetypeExternal.cmake b/Superbuild/FreetypeExternal.cmake
@@ -32,6 +32,7 @@ SET(freetype_GIT_TAG "origin/scirun-5.0.0")
 ExternalProject_Add(Freetype_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/freetype.git"
   GIT_TAG ${freetype_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""

diff --git a/Superbuild/GLMExternal.cmake b/Superbuild/GLMExternal.cmake
@@ -31,6 +31,7 @@ SET_PROPERTY(DIRECTORY PROPERTY "EP_BASE" ${ep_base})
 ExternalProject_Add(GLM_external
   GIT_REPOSITORY "https://github.com/g-truc/glm.git"
   GIT_TAG "0.9.9.8"
+  UPDATE_COMMAND ""
   CONFIGURE_COMMAND ""
   BUILD_COMMAND ""
   INSTALL_COMMAND ""

diff --git a/Superbuild/GlewExternal.cmake b/Superbuild/GlewExternal.cmake
@@ -37,6 +37,7 @@ ENDIF()
 ExternalProject_Add(Glew_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/glew.git"
   GIT_TAG ${glew_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""

diff --git a/Superbuild/GoogleTestExternal.cmake b/Superbuild/GoogleTestExternal.cmake
@@ -38,6 +38,7 @@ SET(googletest_GIT_TAG "origin/cibc")
 ExternalProject_Add(GoogleTest_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/googletest.git"
   GIT_TAG ${googletest_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""

diff --git a/Superbuild/LibPNGExternal.cmake b/Superbuild/LibPNGExternal.cmake
@@ -34,6 +34,7 @@ ExternalProject_Add(LibPNG_external
   DEPENDS ${libpng_DEPENDENCIES}
   GIT_REPOSITORY "https://github.com/CIBC-Internal/libpng.git"
   GIT_TAG ${libpng_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""

diff --git a/Superbuild/LodePngExternal.cmake b/Superbuild/LodePngExternal.cmake
@@ -31,6 +31,7 @@ SET_PROPERTY(DIRECTORY PROPERTY "EP_BASE" ${ep_base})
 ExternalProject_Add(LodePng_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/cibc-lodepng.git"
   GIT_TAG "origin/master"
+  UPDATE_COMMAND ""
   INSTALL_COMMAND ""
   CMAKE_CACHE_ARGS
     -DCMAKE_VERBOSE_MAKEFILE:BOOL=${CMAKE_VERBOSE_MAKEFILE}

diff --git a/Superbuild/PythonExternal.cmake b/Superbuild/PythonExternal.cmake
@@ -91,6 +91,7 @@ IF(UNIX)
   ExternalProject_Add(Python_external
     GIT_REPOSITORY ${python_GIT_URL}
     GIT_TAG ${python_GIT_TAG}
+  UPDATE_COMMAND ""
     BUILD_IN_SOURCE ON
     CONFIGURE_COMMAND ./configure ${python_CONFIGURE_FLAGS}
     PATCH_COMMAND ""
@@ -107,6 +108,7 @@ ELSE()
   ExternalProject_Add(Python_external
     GIT_REPOSITORY ${python_GIT_URL}
     GIT_TAG ${python_GIT_TAG}
+  UPDATE_COMMAND ""
     PATCH_COMMAND ""
     CONFIGURE_COMMAND PCbuild/build.bat
     BUILD_IN_SOURCE ON

diff --git a/Superbuild/SQLiteExternal.cmake b/Superbuild/SQLiteExternal.cmake
@@ -32,6 +32,7 @@ SET(sqlite_GIT_TAG "origin/scirun-5.0.0-beta")
 ExternalProject_Add(SQLite_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/sqlite.git"
   GIT_TAG ${sqlite_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""

diff --git a/Superbuild/SpdLogExternal.cmake b/Superbuild/SpdLogExternal.cmake
@@ -31,6 +31,7 @@ SET_PROPERTY(DIRECTORY PROPERTY "EP_BASE" ${ep_base})
 ExternalProject_Add(SpdLog_external
   GIT_REPOSITORY "https://github.com/gabime/spdlog"
   GIT_TAG "v1.10.0"
+  UPDATE_COMMAND ""
   CONFIGURE_COMMAND ""
   BUILD_COMMAND ""
   INSTALL_COMMAND ""

diff --git a/Superbuild/Superbuild.cmake b/Superbuild/Superbuild.cmake
@@ -28,6 +28,8 @@
 # TODO: build from archive - Git not used
 SET(compress_type "GIT" CACHE INTERNAL "")
 SET(ep_base "${CMAKE_BINARY_DIR}/Externals" CACHE INTERNAL "")
+SET_PROPERTY(DIRECTORY PROPERTY "EP_BASE" ${ep_base})
+SET_PROPERTY(DIRECTORY PROPERTY "EP_UPDATE_DISCONNECTED" TRUE)
 
 ###########################################
 # Force superbuild Python, prevent system Python binding

diff --git a/Superbuild/TeemExternal.cmake b/Superbuild/TeemExternal.cmake
@@ -34,6 +34,7 @@ ExternalProject_Add(Teem_external
   DEPENDS ${teem_DEPENDENCIES}
   GIT_REPOSITORY "https://github.com/SCIInstitute/teem.git"
   GIT_TAG ${teem_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""

diff --git a/Superbuild/TestDataConfig.cmake b/Superbuild/TestDataConfig.cmake
@@ -38,6 +38,7 @@ SET(test_data_DOWNLOAD_DIR "${CMAKE_BINARY_DIR}/download/SCIRunTestData")
 ExternalProject_Add(SCIRunTestData_external
   GIT_REPOSITORY ${test_data_GIT_URL}
   GIT_TAG ${test_data_GIT_TAG}
+  UPDATE_COMMAND ""
   SOURCE_DIR ${test_data_DIR}
   BUILD_COMMAND ""
   CONFIGURE_COMMAND ""

diff --git a/Superbuild/TnyExternal.cmake b/Superbuild/TnyExternal.cmake
@@ -31,6 +31,7 @@ SET_PROPERTY(DIRECTORY PROPERTY "EP_BASE" ${ep_base})
 ExternalProject_Add(Tny_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/Tny.git"
   GIT_TAG "origin/scirun-5.0.0"
+  UPDATE_COMMAND ""
   INSTALL_COMMAND ""
   CMAKE_CACHE_ARGS
     -DCMAKE_VERBOSE_MAKEFILE:BOOL=${CMAKE_VERBOSE_MAKEFILE}

diff --git a/Superbuild/ToolkitsConfig.cmake b/Superbuild/ToolkitsConfig.cmake
@@ -45,6 +45,7 @@ MACRO(EXTERNAL_TOOLKIT name)
   ExternalProject_Add(${toolkit_ExternalProject_name}
     GIT_REPOSITORY "https://github.com/SCIInstitute/${name}.git"
     GIT_TAG ${toolkit_GIT_TAG}
+    UPDATE_COMMAND ""
     BUILD_IN_SOURCE ON
     SOURCE_DIR ${toolkit_DIR}
     BUILD_COMMAND ""

diff --git a/Superbuild/ZlibExternal.cmake b/Superbuild/ZlibExternal.cmake
@@ -32,6 +32,7 @@ SET(zlib_GIT_TAG "origin/1.3.1")
 ExternalProject_Add(Zlib_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/zlib.git"
   GIT_TAG ${zlib_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""