cross-build-test.yml

name: cross-build-test

# mcpp cross-build test — the single source of truth for "which CROSS-build
# target combinations mcpp supports", verified end-to-end.
#
# Cross = host arch ≠ target arch. Verification targets are mcpp ITSELF and
# xlings (real, self-hosting C++23 module projects), cross-built from source for
# each target triple, arch-checked, and smoke-run under qemu-user.
#
# ── Supported cross matrix (built + verified below) ────────────────────────
#   target                | toolchain                        | host→target   | run
#   ----------------------|----------------------------------|---------------|-----
#   aarch64-linux-musl    | aarch64-linux-musl-gcc@16.1.0    | x86_64→arm64  | qemu
#   x86_64-w64-mingw32    | mingw-cross-gcc@16.1.0 (MSVCRT)  | linux→windows | wine
#   x86_64-linux-musl     | x86_64-linux-musl-gcc@16.1.0     | windows→linux | linux job
#
# The mingw row is OS-cross (same arch, different OS/ABI: ELF→PE), so it lives
# in its own job below with wine verification instead of the qemu arch matrix.
# See .agents/docs/2026-07-15-mingw-linux-cross-windows-design.md.
#
# The windows→linux row is the MIRROR of that one, and its verification has no
# wine-equivalent: a Windows runner cannot execute the ELF it just produced.
# So it is split across TWO jobs — build on windows-latest, upload the artefact,
# then download and really run it on ubuntu. Static assertions alone would not
# do: "it linked" has never implied "it runs" (see the elfpatch incident in
# .agents/docs/, and 2026-08-03-windows-host-linux-cross-design.md §6.1).
# The artefact is a fully static musl ELF (no PT_INTERP), so the consumer job
# needs neither qemu nor a matching loader.
#
# mcpp resolves a cross `--target <triple>-musl` build to the triple-named cross
# gcc musl toolchain from the xlings ecosystem (xim:<triple>-gcc, see
# src/build/prepare.cppm). Output is a fully static musl ELF (no PT_INTERP),
# which also makes the aarch64 artefact runnable natively in Termux/Android —
# qemu-aarch64 is the CI proxy for "does this cross artefact actually execute".
#
# ── NOT here ───────────────────────────────────────────────────────────────
#   * The e2e scripts this job names explicitly (102, 1044, ...) are the
#     ones the ordinary Linux shards SKIP for want of `mingw-cross`. They are
#     listed in the job rather than left to run_all's cap gating precisely so
#     they cannot end up skipping everywhere at once. The C++ e2e cases of
#     that kind (198, 240, 248, 923, 1058) are ci-unit.yml's `cases`.
#   * Same-arch builds (host arch == target arch) are NOT cross. The native musl
#     static build `--target x86_64-linux-musl` (x86_64 host) is exercised by
#     ci-linux.yml's "Toolchain: musl-gcc" step, and release.yml for the static
#     release artefact. Keep them there; this file is cross-arch only.
#
# ── Planned cross rows (documented; NOT yet wired in mcpp — keep as comments) ─
#   * llvm/clang cross  : clang is inherently a cross-compiler, but mcpp does not
#                         yet inject `-target <triple>` + a cross sysroot for a
#                         clang toolchain; cross `--target` resolves to gcc musl
#                         only. Wire the clang cross path first, then add a row.
#   * riscv64-linux-musl: add once xim:riscv64-linux-musl-gcc ships to
#                         xlings-res + xim-pkgindex.

on:
  workflow_call:

jobs:
  cross-build:
    name: cross-build ${{ matrix.target }} (mcpp + xlings)
    runs-on: ubuntu-24.04
    timeout-minutes: 60
    strategy:
      fail-fast: false
      matrix:
        include:
          - target: aarch64-linux-musl
            file_arch: "ARM aarch64"
            qemu_bin: qemu-aarch64-static
    env:
      MCPP_HOME: /home/runner/.mcpp
      # Verbose every mcpp invocation for richer CI diagnostics (src/cli.cppm).
      MCPP_VERBOSE: "1"
    steps:
      - uses: actions/checkout@v4

      # Restored here and saved by this job alone, on main, after its last
      # step (rule R3 of the 2026-10-02 CI record).
      - name: Restore mcpp sandbox
        id: sandbox
        uses: actions/cache/restore@v4
        with:
          path: ~/.mcpp
          key: mcpp-sandbox-${{ runner.os }}-cross-${{ matrix.target }}-${{ hashFiles('mcpp.toml', '.xlings.json', '.github/workflows/cross-build-test.yml') }}
          restore-keys: |
            mcpp-sandbox-${{ runner.os }}-cross-${{ matrix.target }}-

      - name: Restore xlings
        id: xlings
        uses: actions/cache/restore@v4
        with:
          path: ~/.xlings
          key: xlings-${{ runner.os }}-cross-v3-${{ hashFiles('.xlings.json') }}
          restore-keys: |
            xlings-${{ runner.os }}-cross-v3-

      - name: Install qemu-user-static
        run: |
          # The runner image carries third-party apt lists (Google Chrome
          # among them) that this job does not use, and a transient
          # `Hash Sum mismatch` on one of them fails the whole update -- which
          # killed two cross-build jobs in setup, before a single byte was
          # compiled. Dropping the lists this job has no use for is what makes
          # the step's failure mean something about this job.
          #
          # BY CONTENT, NOT BY FILENAME. The first attempt removed
          # `google-chrome.list` and the update failed on the same URL: on
          # ubuntu-24.04 the runner writes deb822 `.sources` files, so the
          # name was a guess and the guess was wrong.
          sudo grep -rlE 'dl[.]google[.]com|packages[.]microsoft[.]com' \
               /etc/apt/sources.list.d/ 2>/dev/null | xargs -r sudo rm -f
          sudo apt-get update -qq
          sudo apt-get install -y qemu-user-static
          ${{ matrix.qemu_bin }} --version | head -1

      - name: Bootstrap mcpp via xlings
        env:
          XLINGS_NON_INTERACTIVE: '1'
          # Must equal `pinned::kXlingsVersion` (src/provider/xlings/xlings.cppm) and the
          # xlings the release bundles — enforced by
          # .github/tools/check_version_pins.sh.
          #
          # Floors worth remembering. 0.4.67 carried the
          # multi-index_repo install fix (openxlings/xlings#374); 0.4.68 adds
          # per-repo index artifact sources (openxlings/xlings#377) so the
          # mcpplibs index syncs via artifact with git as fallback (mcpp#269);
          # 0.4.69 keys the index by (namespace, name) so two packages sharing
          # a short name in ONE index are both addressable (openxlings/xlings#381)
          # — the floor for SPEC-001 short-name descriptors.
          # A past 0.4.61 "download 404
          # for mcpp@<pin>" was NOT a version bug — the xlings-res/mcpp GitHub
          # release assets were uploaded in a broken state (records present,
          # blobs missing → 404 on GET); re-uploaded clean. The stale-INDEX
          # half is handled by the marker-clear below.
          XLINGS_VERSION: '2026.10.26.1'
        run: |
          tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
          bash "$GITHUB_WORKSPACE/.github/tools/fetch_release.sh" \
            "https://github.com/d2learn/xlings/releases/download/v${XLINGS_VERSION}/${tarball}" \
            "/tmp/${tarball}"
          tar -xzf "/tmp/${tarball}" -C /tmp
          "/tmp/xlings-${XLINGS_VERSION}-linux-x86_64/subos/default/bin/xlings" self install
          export PATH="$HOME/.xlings/subos/default/bin:$PATH"
          xlings --version
          # Force a real index re-sync even on a warm cache: drop the TTL refresh
          # markers so `xlings update` actually pulls the latest index (sees the
          # current bootstrap pin) while the toolchain payloads stay cached.
          find "$HOME/.xlings" -name '.xlings-index-cache.json' -delete 2>/dev/null || true
          xlings config --mirror GLOBAL 2>/dev/null || true
          xlings update -y 2>/dev/null || xlings update 2>/dev/null || true
          # MCPP_BOOT is what actually runs the bootstrap build below, so it —
          # not just MCPP — has to be the pinned binary. It used to be the shim
          # in subos/default/bin, which resolves to whatever version xvm has
          # selected; pinning only MCPP would have looked right and changed
          # nothing.
          MCPP_BOOT=$(bash "$GITHUB_WORKSPACE/.github/tools/install_pinned_mcpp.sh" "$GITHUB_WORKSPACE")
          echo "MCPP=$MCPP_BOOT" >> "$GITHUB_ENV"
          echo "XLINGS_BIN=$HOME/.xlings/subos/default/bin/xlings" >> "$GITHUB_ENV"
          echo "MCPP_BOOT=$MCPP_BOOT" >> "$GITHUB_ENV"

      - uses: ./.github/actions/use-built-mcpp
        with:
          host: linux-x86_64

      - name: "Cross-build mcpp -> ${{ matrix.target }}"
        run: |
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          bin=$(bash "$GITHUB_WORKSPACE/.github/tools/built_artifact.sh" "$MCPP" mcpp --target ${{ matrix.target }})
          [ -n "$bin" ] || { echo "no mcpp artefact for ${{ matrix.target }}"; exit 1; }
          echo "== file =="; file "$bin"
          file "$bin" | grep -q "${{ matrix.file_arch }}" || { echo "expected ${{ matrix.file_arch }}"; exit 1; }
          file "$bin" | grep -q "statically linked" || { echo "expected static"; exit 1; }
          echo "MCPP_XBIN=$bin" >> "$GITHUB_ENV"

      - name: "Cross-build xlings -> ${{ matrix.target }}"
        run: |
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          # A hosted runner's DNS hiccup is not a red build — see
          # .github/tools/git_clone_retry.sh for the measurement.
          "$GITHUB_WORKSPACE/.github/tools/git_clone_retry.sh" \
            --depth 1 https://github.com/openxlings/xlings /tmp/xlings-src
          cd /tmp/xlings-src
          "$MCPP" self config --mirror GLOBAL 2>/dev/null || true
          xbin=$(bash "$GITHUB_WORKSPACE/.github/tools/built_artifact.sh" "$MCPP" xlings --target ${{ matrix.target }})
          [ -n "$xbin" ] || { echo "no xlings artefact for ${{ matrix.target }}"; exit 1; }
          echo "== file =="; file "$xbin"
          file "$xbin" | grep -q "${{ matrix.file_arch }}" || { echo "expected ${{ matrix.file_arch }}"; exit 1; }
          file "$xbin" | grep -q "statically linked" || { echo "expected static"; exit 1; }
          echo "XLINGS_XBIN=$xbin" >> "$GITHUB_ENV"

      - name: "Smoke-run cross artefacts under qemu"
        run: |
          RUN="${{ matrix.qemu_bin }}"
          # mcpp is self-contained, so --version runs cleanly under bare qemu —
          # this is the hard execution proof for the cross artefact.
          echo "== mcpp --version =="
          mver=$($RUN "$MCPP_XBIN" --version)
          echo "$mver"; echo "$mver" | grep -q "mcpp" || { echo "mcpp --version failed"; exit 1; }
          # xlings expects a real runtime environment (sandbox/config) and may
          # exit non-zero on a bare `--version` under qemu; its ELF arch + static
          # linkage were already asserted in the build step, so treat execution
          # here as best-effort rather than gating.
          echo "== xlings --version (best-effort under qemu) =="
          xver=$($RUN "$XLINGS_XBIN" --version 2>&1 || true)
          echo "$xver"

      - name: Save mcpp sandbox
        if: ${{ github.event_name == 'push' && steps.sandbox.outputs.cache-hit != 'true' }}
        uses: actions/cache/save@v4
        with:
          path: ~/.mcpp
          key: ${{ steps.sandbox.outputs.cache-primary-key }}

      - name: Save xlings
        if: ${{ github.event_name == 'push' && steps.xlings.outputs.cache-hit != 'true' }}
        uses: actions/cache/save@v4
        with:
          path: ~/.xlings
          key: ${{ steps.xlings.outputs.cache-primary-key }}

  # ── Linux → Windows MinGW cross (OS-cross, same arch: ELF→PE) ─────────────
  # Builds a demo project for x86_64-w64-mingw32 with the from-source GCC-16
  # MSVCRT cross toolchain, asserts the artefact is a fully-static PE, and runs
  # it under wine. Delegated to the e2e harness (tests/e2e/102_mingw_cross_wine.sh,
  # `# requires: mingw-cross wine`) so the run_all cap-gating stays the single
  # source of truth. See 2026-07-15-mingw-linux-cross-windows-design.md Part C.
  mingw-cross-wine:
    name: mingw-cross linux→windows (build + wine run)
    runs-on: ubuntu-24.04
    timeout-minutes: 60
    env:
      MCPP_HOME: /home/runner/.mcpp
      MCPP_VERBOSE: "1"
    steps:
      - uses: actions/checkout@v4

      # Restored here and saved by this job alone, on main, after its last
      # step (rule R3). The Wine packages were evicted with everything else
      # while the repository's caches exceeded their limit, and `apt` then
      # took 26 to 50 minutes (2026-10-01); with one writer per key they stay.
      - name: Restore mcpp sandbox
        id: sandbox
        uses: actions/cache/restore@v4
        with:
          path: ~/.mcpp
          key: mcpp-sandbox-${{ runner.os }}-mingw-cross-${{ hashFiles('mcpp.toml', '.xlings.json', '.github/workflows/cross-build-test.yml') }}
          restore-keys: |
            mcpp-sandbox-${{ runner.os }}-mingw-cross-

      - name: Restore xlings
        id: xlings
        uses: actions/cache/restore@v4
        with:
          path: ~/.xlings
          key: xlings-${{ runner.os }}-mingw-cross-v3-${{ hashFiles('.xlings.json') }}
          restore-keys: |
            xlings-${{ runner.os }}-mingw-cross-v3-

      # THE KEY NAMES THE RUNNER IMAGE, because the image is what the cached
      # packages have to agree with. Wine's i386 closure is Multi-Arch: same
      # with the amd64 libraries the image ships, and the two must be one
      # version. Under the old fixed key (`-v1`) the cache was saved once and
      # never again, the image moved on, and on 2026-10-15 (run 38695300904,
      # a cache HIT) the cached libxml2:i386 3.9 met the image's
      # libxml2:amd64 3.10: dpkg installed the stale i386 package, apt then
      # upgraded it, and the upgrade's shared changelog was refused. A new
      # image is a new key; until main has saved it, `restore-keys` hands back
      # the previous image's packages, which the step below only uses where
      # their version is still the one apt asks for.
      - name: Runner image version
        id: image
        run: echo "version=${ImageVersion:-unknown}" >> "$GITHUB_OUTPUT"

      - name: Restore wine debs
        id: wine
        uses: actions/cache/restore@v4
        with:
          path: ~/wine-debs
          key: wine-debs-${{ runner.os }}-ubuntu24.04-${{ steps.image.outputs.version }}
          restore-keys: |
            wine-debs-${{ runner.os }}-ubuntu24.04-

      # APT INSTALLS, ALWAYS; THE CACHE ONLY SPARES IT THE DOWNLOAD. The cached
      # packages are put where apt keeps what it downloaded, and apt then
      # resolves wine against the image as it is today: a cached package whose
      # version is still current is used as is, anything newer is fetched.
      # Nothing older than the image is ever installed, which is what
      # `dpkg -i` of the cached set did whenever the image had moved on. Cold
      # (no cache at all), this is the plain install it always was.
      - name: Install wine
        timeout-minutes: 20
        run: |
          sudo dpkg --add-architecture i386 || true
          # The runner image carries third-party apt lists (Google Chrome
          # among them) that this job does not use, and a transient
          # `Hash Sum mismatch` on one of them fails the whole update -- which
          # killed two cross-build jobs in setup, before a single byte was
          # compiled. Dropping the lists this job has no use for is what makes
          # the step's failure mean something about this job.
          #
          # BY CONTENT, NOT BY FILENAME. The first attempt removed
          # `google-chrome.list` and the update failed on the same URL: on
          # ubuntu-24.04 the runner writes deb822 `.sources` files, so the
          # name was a guess and the guess was wrong.
          sudo grep -rlE 'dl[.]google[.]com|packages[.]microsoft[.]com' \
               /etc/apt/sources.list.d/ 2>/dev/null | xargs -r sudo rm -f
          if ls ~/wine-debs/*.deb >/dev/null 2>&1; then
            sudo cp ~/wine-debs/*.deb /var/cache/apt/archives/
          fi
          sudo apt-get update -qq
          sudo apt-get install -y --download-only wine64 wine \
            || sudo apt-get install -y --download-only wine
          # What main saves is what this image installs: packages no longer
          # in any index (the previous image's, carried in by restore-keys)
          # are dropped first, so the cache does not grow with every image.
          sudo apt-get autoclean -qq
          rm -rf ~/wine-debs && mkdir -p ~/wine-debs
          cp /var/cache/apt/archives/*.deb ~/wine-debs/ 2>/dev/null || true
          sudo apt-get install -y wine64 wine || sudo apt-get install -y wine
          wine --version

      - name: Bootstrap mcpp via xlings
        env:
          XLINGS_NON_INTERACTIVE: '1'
          XLINGS_VERSION: '2026.10.26.1'
        run: |
          tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
          bash "$GITHUB_WORKSPACE/.github/tools/fetch_release.sh" \
            "https://github.com/d2learn/xlings/releases/download/v${XLINGS_VERSION}/${tarball}" \
            "/tmp/${tarball}"
          tar -xzf "/tmp/${tarball}" -C /tmp
          "/tmp/xlings-${XLINGS_VERSION}-linux-x86_64/subos/default/bin/xlings" self install
          export PATH="$HOME/.xlings/subos/default/bin:$PATH"
          find "$HOME/.xlings" -name '.xlings-index-cache.json' -delete 2>/dev/null || true
          xlings config --mirror GLOBAL 2>/dev/null || true
          xlings update -y 2>/dev/null || xlings update 2>/dev/null || true
          # MCPP_BOOT is what actually runs the bootstrap build below, so it —
          # not just MCPP — has to be the pinned binary. It used to be the shim
          # in subos/default/bin, which resolves to whatever version xvm has
          # selected; pinning only MCPP would have looked right and changed
          # nothing.
          MCPP_BOOT=$(bash "$GITHUB_WORKSPACE/.github/tools/install_pinned_mcpp.sh" "$GITHUB_WORKSPACE")
          echo "MCPP=$MCPP_BOOT" >> "$GITHUB_ENV"
          echo "XLINGS_BIN=$HOME/.xlings/subos/default/bin/xlings" >> "$GITHUB_ENV"
          echo "MCPP_BOOT=$MCPP_BOOT" >> "$GITHUB_ENV"

      - uses: ./.github/actions/use-built-mcpp
        with:
          host: linux-x86_64

      # llvm beside it: the case that pairs clang with the MinGW payload reads
      # the program's resources with the payload's llvm-readobj (`llvm`).
      - name: Install mingw-cross toolchain
        run: |
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          "$MCPP" toolchain install mingw-cross 16.1.0
          "$MCPP" toolchain install llvm 23.1.3
          echo "MCPP_VENDORED_XLINGS=$XLINGS_BIN" >> "$GITHUB_ENV"

      - name: "e2e: cross-build + wine run"
        run: |
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          bash tests/e2e/102_mingw_cross_wine.sh

      # SPEC-016 §6: clang with the MinGW-w64 payload as its sysroot, run
      # under wine. Named here for the reason 102 is: `# requires: mingw-cross
      # wine`, which no Linux shard has.
      - name: "e2e: clang pairs with the MinGW payload"
        run: |
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          bash tests/e2e/1044_clang_pairs_with_the_mingw_payload.sh

      # The Windows cases of the C++ e2e suite that need this toolchain run
      # from the test archive in ci-unit.yml (`cases`), beside the Linux shards.

      # SPEC-007 R4.3: the engine places a Windows program's runtime DLLs
      # beside it after its link, so a program started by hand finds them.
      # Named here for the reason the steps above are: the Linux shards skip
      # `# requires: mingw-cross wine`. Each property is held to the line the
      # script prints only when that property was checked.
      # The runtime_search_dir directive on PE (#701): `mcpp run` finds a DLL
      # through PATH and `mcpp pack` places it. The native leg is e2e 794 on
      # the Windows shards; this is its Linux-hosted counterpart.
      - name: "e2e: runtime_search_dir on PE under wine"
        run: |
          set -o pipefail
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          log="$RUNNER_TEMP/796.log"
          bash tests/e2e/796_runtime_search_dir_on_pe_under_wine.sh 2>&1 | tee "$log"
          grep -qxF "PASS: 796_runtime_search_dir_on_pe_under_wine" "$log" \
            || { echo "::error::796 did not print its PASS line"; exit 1; }

      - name: "e2e: a Windows program finds its runtime DLLs beside it"
        run: |
          set -o pipefail
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          log="$RUNNER_TEMP/797.log"
          bash tests/e2e/797_a_windows_program_finds_its_dlls_beside_it.sh 2>&1 | tee "$log"
          for line in \
            "  ok: after the first build the program started by hand finds its DLL" \
            "  ok: a build with nothing changed neither relinks nor places again" \
            "  ok: a DLL replaced in its directory replaces the copy" \
            "  ok: no system DLL is copied" \
            "PASS: a Windows program finds its runtime DLLs beside it"; do
            grep -qxF "$line" "$log" || { echo "::error::797 did not print: $line"; exit 1; }
          done

      # The Windows launcher of an ok-image tree (`bin/<name>.exe`, built over
      # the platform's hosted arrangement) finds its package from a Windows
      # path. The shards have no wine; this job does.
      - name: "e2e: the Windows launcher finds its package from a Windows path (988)"
        run: |
          set -o pipefail
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          log="$RUNNER_TEMP/988.log"
          bash tests/e2e/988_the_windows_launcher_finds_its_package_from_a_windows_path.sh 2>&1 | tee "$log"
          grep -qxF "PASS: 988 the Windows launcher finds its package from a Windows path" "$log" \
            || { echo "::error::988 did not print its PASS line"; exit 1; }

      # The MinGW-w64 base package beside llvm (design 2026-11-10 E9): the
      # program runs under wine, which only this job has.
      - name: "e2e: a mingw base package serves windows-gnu beside llvm (1063)"
        run: |
          set -o pipefail
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          log="$RUNNER_TEMP/1063.log"
          bash tests/e2e/1063_a_mingw_base_package_serves_windows_gnu_beside_llvm.sh 2>&1 | tee "$log"
          grep -qxF "PASS: 1063 a mingw base package serves windows-gnu beside llvm" "$log" \
            || { echo "::error::1063 did not print its PASS line"; exit 1; }

      # A polyglot file (SPEC-014 §5.3) is the Windows program as it is: its
      # criterion H runs the file under wine, which only this job has.
      - name: "e2e: a polyglot file runs on every system it holds (992)"
        run: |
          set -o pipefail
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          log="$RUNNER_TEMP/992.log"
          bash tests/e2e/992_a_polyglot_file_runs_on_every_system_it_holds.sh 2>&1 | tee "$log"
          grep -qxF "ok: the file is a Windows program" "$log" \
            || { echo "::error::992 did not run the file under wine"; exit 1; }

      # 257 needs a Linux-hosted MinGW compiler AND wine, which only this job
      # has; on the shards it skipped, and it had run on no runner (finding F9
      # of the 2026-10-02 CI record).
      - name: "e2e: a shared library across the PE boundary (257)"
        run: |
          set -o pipefail
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          log="$RUNNER_TEMP/257.log"
          bash tests/e2e/257_shared_library_pe.sh 2>&1 | tee "$log"
          if grep -q '^SKIP' "$log"; then
            echo "::error::257 skipped on the job that can run it"; exit 1
          fi

      - name: Save mcpp sandbox
        if: ${{ github.event_name == 'push' && steps.sandbox.outputs.cache-hit != 'true' }}
        uses: actions/cache/save@v4
        with:
          path: ~/.mcpp
          key: ${{ steps.sandbox.outputs.cache-primary-key }}

      - name: Save xlings
        if: ${{ github.event_name == 'push' && steps.xlings.outputs.cache-hit != 'true' }}
        uses: actions/cache/save@v4
        with:
          path: ~/.xlings
          key: ${{ steps.xlings.outputs.cache-primary-key }}

      - name: Save wine debs
        if: ${{ github.event_name == 'push' && steps.wine.outputs.cache-hit != 'true' }}
        uses: actions/cache/save@v4
        with:
          path: ~/wine-debs
          key: ${{ steps.wine.outputs.cache-primary-key }}

  # ── windows → linux ───────────────────────────────────────────────────────
  # The mirror of mingw-cross-wine. Two jobs because a Windows runner cannot
  # execute the ELF it produces; the artefact is handed to a Linux job and
  # really run there.
  windows-host-linux-cross:
    name: windows→linux cross-build (windows host)
    runs-on: windows-latest
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v4
      # No job restores target/ any more. This one was the first to stop: a
      # restored BMI tree beside a fresh one made GCC report
      # `import 'std' has CRC mismatch` on the second of its two builds.
      - uses: ./.github/actions/bootstrap-mcpp

      - uses: ./.github/actions/use-built-mcpp
        with:
          host: windows-x86_64

      - name: Name this commit's mcpp MCPP_SELF
        shell: bash
        run: |
          "$MCPP_FRESH" --version
          echo "MCPP_SELF=$MCPP_FRESH" >> "$GITHUB_ENV"

      - name: Install the linux-musl cross toolchain (windows-hosted canadian)
        shell: bash
        run: |
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          "$MCPP_SELF" toolchain install gcc 16.1.0 --target x86_64-linux-musl
          # The target row must now be visible on a Windows host — this is the
          # host gate from design §1.2 having been lifted, asserted rather than
          # eyeballed.
          "$MCPP_SELF" toolchain list | tee /tmp/tclist.txt
          grep -q "x86_64-linux-musl" /tmp/tclist.txt \
            || { echo "FAIL: linux-musl target not listed on windows host"; exit 1; }

      - name: "Cross-build mcpp -> x86_64-linux-musl"
        shell: bash
        run: |
          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
          "$MCPP_SELF" build --target x86_64-linux-musl
          # Scope the search to the TARGET's output tree — target/ also holds the
          # host build from the previous step, and both are named "mcpp*".
          #
          # The artefact carries a `.exe` suffix even though it is an ELF:
          # plan.cppm's target_output() spells the suffix from
          # mcpp::platform::exe_suffix, a HOST constant. That is the same
          # host-decides-target confusion as B2, and it is symmetric — a
          # Linux→Windows cross produces a PE with no `.exe` today. Renaming the
          # output is a behaviour change that would touch the mingw e2e and any
          # user script, so it is filed as follow-up rather than folded in here;
          # match both spellings so this job is correct either way.
          OUT=$(find target/x86_64-linux-musl -type f -path "*/bin/*" \
                     \( -name "mcpp" -o -name "mcpp.exe" \) -printf "%T@ %p\n" \
              | sort -rn | head -1 | cut -d" " -f2-)
          if [ -z "$OUT" ]; then
            echo "FAIL: no cross artefact produced; tree was:"
            find target/x86_64-linux-musl -type f -path "*/bin/*" | head -20
            exit 1
          fi
          cp "$OUT" mcpp-linux-musl
          ls -la mcpp-linux-musl

      - uses: actions/upload-artifact@v4
        with:
          name: mcpp-x86_64-linux-musl-from-windows
          path: mcpp-linux-musl
          retention-days: 1

  windows-host-linux-cross-run:
    name: windows→linux artefact really runs (linux)
    needs: windows-host-linux-cross
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: mcpp-x86_64-linux-musl-from-windows

      - name: Assert it is a static ELF, then run it
        run: |
          set -euo pipefail
          chmod +x mcpp-linux-musl
          file mcpp-linux-musl

          # B2 regression gate (design §1.3): before the fix, `-static` was
          # decided by a HOST constant (`supports_full_static = is_linux`), so
          # a Windows host emitted a NON-static binary here. Written as a
          # positive `grep -q` on purpose: `! cmd | grep` is exempt from
          # errexit and can never fail (see build-mcpp-helper-self-containment).
          file mcpp-linux-musl | grep -q "ELF 64-bit LSB"
          file mcpp-linux-musl | grep -q "x86-64"
          file mcpp-linux-musl | grep -q "statically linked"

          # A static musl ELF has no PT_INTERP at all — the stronger form of
          # the same claim, and independent of `file`'s wording.
          readelf -l mcpp-linux-musl > hdrs.txt
          if grep -q "INTERP" hdrs.txt; then
            echo "FAIL: artefact has a PT_INTERP segment — not statically linked"
            grep -A2 "INTERP" hdrs.txt
            exit 1
          fi

          # Linked ≠ runs. This is the whole point of the second job.
          ./mcpp-linux-musl --version
          ./mcpp-linux-musl --help > /dev/null
          echo "OK: windows-built linux artefact executes natively"