From fd41eaef61a38f4675a11c4d766bb4c5c80affe4 Mon Sep 17 00:00:00 2001
From: Lukas Burgholzer <burgholzer@me.com>
Date: Mon, 5 Oct 2026 11:53:01 +0000
Subject: [PATCH] =?UTF-8?q?=E2=9A=A1=20Cache=20wheel=20builds=20with=20scc?=
 =?UTF-8?q?ache?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Configure the supported sccache action and CMake compiler launchers for wheel
builds. Match the existing main-only cache write policy, retain statistics for
long jobs, and document the Linux container environment handoff.

Assisted-by: GPT-6 via Codex
---
 ...le-python-packaging-wheel-cibuildwheel.yml | 19 +++++++------
 CHANGELOG.md                                  |  8 ++++++
 UPGRADING.md                                  | 27 +++++++++++++++++++
 3 files changed, 44 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/reusable-python-packaging-wheel-cibuildwheel.yml b/.github/workflows/reusable-python-packaging-wheel-cibuildwheel.yml
index fd3e6f83..6e30ecdf 100644
--- a/.github/workflows/reusable-python-packaging-wheel-cibuildwheel.yml
+++ b/.github/workflows/reusable-python-packaging-wheel-cibuildwheel.yml
@@ -58,6 +58,11 @@ jobs:
     name: 🎡 ${{ inputs.runs-on }}
     runs-on: ${{ inputs.runs-on }}
     env:
+      CMAKE_C_COMPILER_LAUNCHER: sccache
+      CMAKE_CXX_COMPILER_LAUNCHER: sccache
+      SCCACHE_GHA_ENABLED: true
+      SCCACHE_IDLE_TIMEOUT: 0
+      SCCACHE_GHA_RW_MODE: ${{ github.ref == 'refs/heads/main' && 'READ_WRITE' || 'READ_ONLY' }}
       IQM_TOKEN: ${{ secrets.IQM_TOKEN }}
       IQM_QC_ALIAS: ${{ secrets.IQM_QC_ALIAS }}
       AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
@@ -89,13 +94,11 @@ jobs:
           enable-cache: ${{ !startsWith(inputs.runs-on, 'ubuntu') }}
           save-cache: ${{ github.ref == 'refs/heads/main' }}
 
-      # set up sccache for faster builds (non-Ubuntu only)
-      - name: Install sccache
-        if: ${{ !startsWith(inputs.runs-on, 'ubuntu') }}
-        run: uv tool install sccache
+      - name: Set up sccache
+        uses: mozilla-actions/sccache-action@fc920bf0ec8de6ee65d409111f7ec508035751ba # v0.0.11
 
-      # run cibuildwheel to build wheels for the specified Python version
-      - uses: pypa/cibuildwheel@adba99c781d3746d38b3a09b1cf797965bcb7fe6 # v4.3.0
+      - name: Build wheels
+        uses: pypa/cibuildwheel@adba99c781d3746d38b3a09b1cf797965bcb7fe6 # v4.3.0
 
       - name: Verify clean directory
         run: git diff --exit-code
@@ -107,7 +110,3 @@ jobs:
         with:
           name: ${{ github.event_name == 'pull_request' && 'dev-' || '' }}cibw-wheels-${{ inputs.runs-on }}
           path: wheelhouse/*.whl
-
-      - name: Show sccache stats
-        if: ${{ !startsWith(inputs.runs-on, 'ubuntu') }}
-        run: sccache --show-stats
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 80b31103..ae9c0cbb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,13 @@ releases may include breaking changes.
 
 ## [Unreleased]
 
+### Changed
+
+- ⚡ Enable shared `sccache` for native wheel builds through the supported
+  action. Only `main` writes to the cache; other refs read from it. Linux
+  consumers forward the cache environment into cibuildwheel containers ([#464])
+  ([**@burgholzer**])
+
 ## [2.5.1] - 2026-10-07
 
 _If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md#251)._
@@ -623,6 +630,7 @@ _📚 Refer to the [GitHub Release Notes] for previous changelogs._
 [#474]: https://github.com/munich-quantum-toolkit/workflows/pull/474
 [#472]: https://github.com/munich-quantum-toolkit/workflows/pull/472
 [#470]: https://github.com/munich-quantum-toolkit/workflows/pull/470
+[#464]: https://github.com/munich-quantum-toolkit/workflows/pull/464
 [#463]: https://github.com/munich-quantum-toolkit/workflows/pull/463
 [#462]: https://github.com/munich-quantum-toolkit/workflows/pull/462
 [#461]: https://github.com/munich-quantum-toolkit/workflows/pull/461
diff --git a/UPGRADING.md b/UPGRADING.md
index beed8966..4fa7cdf4 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -6,6 +6,33 @@ of changes, including minor and patch releases, please refer to the
 
 ## [Unreleased]
 
+### Wheel compiler caching
+
+The cibuildwheel workflow now configures CMake compiler launchers and the GitHub
+Actions `sccache` backend. Only `main` writes to the cache; other refs read from
+it. Project CMake settings must preserve the supplied launcher environment
+variables and use a generator that supports compiler launchers, such as Ninja.
+
+Linux builds must install `sccache` inside their cibuildwheel containers and
+append these variables to `[tool.cibuildwheel.linux].environment-pass`:
+
+```toml
+environment-pass = [
+  "CMAKE_C_COMPILER_LAUNCHER",
+  "CMAKE_CXX_COMPILER_LAUNCHER",
+  "SCCACHE_GHA_ENABLED",
+  "SCCACHE_GHA_RW_MODE",
+  "SCCACHE_IDLE_TIMEOUT",
+  "ACTIONS_CACHE_SERVICE_V2",
+  "ACTIONS_RESULTS_URL",
+  "ACTIONS_RUNTIME_TOKEN",
+]
+```
+
+The action reports host-side statistics automatically. Linux projects can
+inspect container-side statistics in their cibuildwheel build hooks with
+`sccache --show-stats`.
+
 ## [2.5.1]
 
 MLIR-enabled workflows default to LLVM 23.1.2; set `llvm-version` explicitly to