ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:
    inputs:
      mcpp_ref:
        description: "Branch of mcpp-community/mcpp to build and test against (empty = the released pin)"
        required: false
        default: ""
env:
  MCPP_SOURCE_REF: ${{ github.event.inputs.mcpp_ref || vars.MCPP_SOURCE_REF }}

jobs:
  build:
    name: boots under real OpenSBI
    runs-on: ubuntu-24.04
    timeout-minutes: 40
    env:
      MCPP_VERSION: 2026.8.25.2
      XLINGS_VERSION: v2026.8.17.2
      XLINGS_NON_INTERACTIVE: '1'
      # The branch of the specification this backend is verified against. It
      # moves with this one; when both are on `main` this becomes `main`.
      # The specification is taken from the branch of the same name where
      # one exists, so a change spanning both repositories is tested as a
      # whole. It was a fixed branch name until 2026-08-25 --- one merged
      # long before, so every run since had been cloning a stale tree and
      # reporting on it.
      OPENKAL_BRANCH: ${{ github.head_ref || github.ref_name }}
    steps:
      - uses: actions/checkout@v4

      - name: Install xlings
        run: |
          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh \
            | bash -s "$XLINGS_VERSION"
          echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"

      - name: Install mcpp
        run: |
          # ⚠️ A LOOP, BECAUSE ONE `xlings update` CAN RETURN A STALE INDEX
          # WITHOUT SAYING SO.
          #
          # The index is published as an artifact behind a pointer, and that
          # pointer propagates asynchronously after a version bump is merged.
          # Measured on release day: an update run four minutes after the merge
          # printed `index updated`, and the install then failed with
          #
          #     package 'mcpp@<ver>' not found in the synced index
          #     (xim@artifact:<an older sha>, ...), synced 0 seconds ago
          #
          # Nothing had gone wrong. The update fetched the PREVIOUS artifact,
          # and "synced 0 seconds ago" describes when it was fetched rather than
          # what it contains — which is why the message reads as freshness.
          #
          # So this is not a retry around flakiness; it is the wait that a
          # single update does not perform. A pin naming a version that was
          # never published still fails, after the last attempt, and says which
          # of the two situations it is.
          for attempt in 1 2 3 4 5 6; do
            xlings update > /dev/null 2>&1 || true
            if # ⚠️ THE PIN MAY NAME THE RELEASE THIS RUN IS VALIDATING, which does
          # not exist yet — that is the whole point of MCPP_SOURCE_REF. Bootstrap
          # from whatever the index has; the step below replaces it with the
          # build under review, and the pin is what an ordinary run tests.
          if [ -n "${MCPP_SOURCE_REF:-}" ]; then
            xlings install mcpp -y -g
          else
            xlings install "mcpp@$MCPP_VERSION" -y -g
          fi; then break; fi
            if [ "$attempt" = 6 ]; then
              echo "::error::mcpp@$MCPP_VERSION never appeared in the index (6 attempts over 5 minutes). If it was just released, the pointer has not propagated; if the pin names a version that was never published, it never will."
              exit 1
            fi
            echo "the index has not caught up yet (attempt $attempt of 6); waiting 60s"
            sleep 60
          done
          mcpp --version
          mcpp self config --mirror GLOBAL
          # ⭐⭐ CROSS-VALIDATION: BUILD THE mcpp UNDER REVIEW AND USE THAT ONE.
          #
          # Empty in the ordinary run, so this job keeps testing the RELEASED
          # mcpp the pin above names. Set it — `workflow_dispatch` input, or the
          # repository variable — and the same job runs against that source.
          #
          # ⚠️ THIS EXISTS BECAUSE THE ORDER USED TO BE WRONG. Several mcpp
          # releases went out green and only then turned this ecosystem red: the
          # engine's own CI cannot see a defect that appears only in a real
          # dependency graph, and this repository could not see the engine until
          # it had been published. Validating before the release closes that gap.
          #
          # The released mcpp installed just above is the bootstrap that compiles
          # it; mcpp builds itself and there is no other compiler for it here.
          if [ -n "${MCPP_SOURCE_REF:-}" ]; then
            src="$RUNNER_TEMP/mcpp-src"
            [ -d "$src" ] || git clone --quiet --depth 1 \
              --branch "$MCPP_SOURCE_REF" \
              https://github.com/mcpp-community/mcpp.git "$src"
            # ⚠️ THE CLONE'S OWN WORKSPACE PIN MUST NOT DECIDE WHICH mcpp
            # BUILDS IT. `.xlings.json` at mcpp's root pins the mcpp that
            # compiles mcpp, and that pin does not move when mcpp is released —
            # so a build inside the checkout obeys it and tries to install a
            # version the index may no longer carry:
            #
            #     [error] xlings: version '2026.8.17.1' not found for 'mcpp'
            #       available: 2026.8.25.1
            #
            # What is wanted here is the source compiled by the mcpp installed
            # above, which is exactly what removing the file leaves.
            rm -f "$src/.xlings.json"
            ( cd "$src" && mcpp build --release )
            # ⭐ `$src` is a FRESH clone each run, so `target/` holds exactly what
            # this step just built and there is no earlier fingerprint directory
            # to pick by mistake. `-printf` would be the safer form on a cached
            # tree and is a GNU extension this must not use — one of the runners
            # that reaches this line is macOS.
            built=$(find "$src/target" -type f -name mcpp -perm -u+x | head -1)
            [ -n "$built" ] || { echo "::error::mcpp did not build from $MCPP_SOURCE_REF"; exit 1; }
            echo "$(cd "$(dirname "$built")" && pwd)" >> "$GITHUB_PATH"
            # ⚠️ Reported, because a PATH entry that does not win looks exactly
            # like one that does until something built with the wrong engine.
            echo "under review: $("$built" --version)  (from $MCPP_SOURCE_REF)"
          fi

      - name: Install the emulator
        run: |
          # Both homes: the shim on PATH dispatches against whichever home owns
          # it, while mcpp starts the runner through its own.
          xlings install xim:qemu-riscv -y
          XLINGS_HOME="$HOME/.mcpp/registry" xlings install xim:qemu-riscv -y

      # ⚠️ The assertion is on the OUTPUT, not on the exit status. A firmware
      # that never reaches the payload exits zero, and so does a payload whose
      # console writes go nowhere — which is precisely the failure this backend
      # exists to avoid on a second machine.
      - name: The example prints under `-bios default`
        run: |
          set -euo pipefail
          cd examples/hello
          Q=$(ls -d "$HOME"/.mcpp/registry/data/xpkgs/xim-x-qemu-riscv/*/bin/qemu-system-riscv64 | head -1)
          sed -i "s|\"qemu-system-riscv64\"|\"$Q\"|" mcpp.toml
          mcpp run 2>&1 | tee run.log
          grep -q "hello from openkal over SBI" run.log
          grep -q "heap ok" run.log
          # ⚠️ `clock ok` is the line that distinguishes a counter that reads
          # from a counter that MOVES. The example takes two readings with a
          # sleep between them; a stuck clock reads fine and prints
          # `clock stuck`. Verified to print it, by returning a constant from
          # `kal_time_monotonic` and rerunning.
          grep -q "clock ok" run.log
          grep -q "env empty" run.log

      # ⭐⭐ THE HALF OF CLAUSE 9 THIS BACKEND WAS NOT PERFORMING.
      #
      # The specification makes behavioural conformance a property of every
      # implementation, and three of the four in this ecosystem ran the suite
      # while this one did not. The difficulty was real and it was not that the
      # suite needs an operating system: the suite depends on openkal and the
      # language, does not import std, and states in its own manifest that it is
      # written to run in a program that carries no other runtime.
      #
      # ⚠️ What it needed was three things this environment supplies and a
      # hosted one does not have to, and each was found by trying:
      #
      #   the memory map        — now `openkal-opensbi/board.ld`, reaching the
      #                           suite through this package's build program,
      #                           because where firmware hands control over is a
      #                           fact about this environment and not about any
      #                           program that runs on it;
      #   the hand-over         — `--features standalone`, which is how every
      #                           implementation here performs it when no C
      #                           library is beneath the program;
      #   an entry symbol       — the suite's `main` is `extern "C"`, because
      #                           `-ffreestanding` makes `main` an ordinary
      #                           function and the startup object refers to it
      #                           by name.
      #
      # ⚠️ THE ASSERTION IS ON THE OUTPUT AND ON THE EXIT STATUS BOTH. The suite
      # exits 2 when it observed nothing, which is the outcome a selection that
      # matched no interface would otherwise pass silently — and `core` on a
      # machine with no operating system is exactly the selection where that
      # could happen.
      - name: The conformance suite runs on the machine with no operating system
        run: |
          set -euo pipefail
          git clone --quiet https://github.com/mcpplibs/openkal "$RUNNER_TEMP/spec"
          if git -C "$RUNNER_TEMP/spec" rev-parse --verify --quiet \
               "origin/$OPENKAL_BRANCH" > /dev/null; then
            git -C "$RUNNER_TEMP/spec" checkout --quiet "origin/$OPENKAL_BRANCH"
            echo "the specification is at $OPENKAL_BRANCH"
          else
            echo "the specification has no $OPENKAL_BRANCH; its default branch is used"
          fi
          Q=$(ls -d "$HOME"/.mcpp/registry/data/xpkgs/xim-x-qemu-riscv/*/bin/qemu-system-riscv64 | head -1)
          export OPENKAL_CONFORMANCE_RUNNER="$Q -machine virt -nographic -no-reboot -bios default -kernel"
          export OPENKAL_CONFORMANCE_IMPL_FEATURES=standalone
          cd "$RUNNER_TEMP/spec"
          bash tools/run-conformance.sh openkal-opensbi "$GITHUB_WORKSPACE" core \
            --target riscv64-none-elf 2>&1 | tee conf.log
          grep -q "the implementation conforms in every observation made" conf.log
          # ⚠️ And that something WAS observed. "0 did not hold" is also what a
          # run that examined nothing reports.
          grep -qE "observations: [1-9][0-9]* held" conf.log

  # ---------------------------------------------------------------------------
  # The cross-compilation is performed FROM three systems, not only from Linux.
  #
  # Every target in this repository is a cross target, which makes the host a
  # separate axis from the target: the compiler, the target C library and the
  # emulator are payloads mcpp resolves for whichever system it is running on.
  # A package that has only ever been built from Linux is a package whose
  # consumers must use Linux, and nothing in these sources says so.
  #
  # ⚠️ A TOOLCHAIN AXIS IS ABSENT HERE, AND THAT IS MEASURED RATHER THAN
  # ASSUMED. The row for a bare-metal triple names its compiler, and the
  # command-line override does not displace it: `--toolchain gcc@16.1.0` on a
  # `riscv64-none-elf` build resolves llvm@22.1.8 regardless. A matrix over
  # compiler families would therefore run the same compiler on every row and
  # report coverage it does not have. The toolchain axis belongs where the
  # choice is real — openkal, whose declarations are compiled by three families
  # on three systems.
  #
  # ⚠️ BUILD ONLY, AND DELIBERATELY. Behaviour is asserted once, above, under an
  # emulator. Booting the same image from three systems would be a statement
  # about the emulator rather than about this package, and "the image does what
  # the README says" does not become more true for having been observed from
  # macOS.
  portability:
    name: cross-builds from ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 45
    strategy:
      fail-fast: false
      matrix:
        os: [macos-14, windows-2022]
    defaults:
      run:
        shell: bash
    env:
      MCPP_VERSION: 2026.8.25.2
      XLINGS_VERSION: v2026.8.17.2
      XLINGS_NON_INTERACTIVE: '1'
    steps:
      - uses: actions/checkout@v4

      - name: Install xlings (Unix)
        if: runner.os != 'Windows'
        run: |
          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh \
            | bash -s "$XLINGS_VERSION"
          echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"

      - name: Install xlings (Windows)
        if: runner.os == 'Windows'
        shell: pwsh
        run: |
          irm https://d2learn.org/xlings-install.ps1.txt | iex
          # The installer amends the user's environment; no later step in this
          # job reads it back, so the directory is named here.
          "$env:USERPROFILE\.xlings\subos\current\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append

      - name: Install mcpp
        run: |
          # ⚠️ A LOOP, BECAUSE ONE `xlings update` CAN RETURN A STALE INDEX
          # WITHOUT SAYING SO.
          #
          # The index is published as an artifact behind a pointer, and that
          # pointer propagates asynchronously after a version bump is merged.
          # Measured on release day: an update run four minutes after the merge
          # printed `index updated`, and the install then failed with
          #
          #     package 'mcpp@<ver>' not found in the synced index
          #     (xim@artifact:<an older sha>, ...), synced 0 seconds ago
          #
          # Nothing had gone wrong. The update fetched the PREVIOUS artifact,
          # and "synced 0 seconds ago" describes when it was fetched rather than
          # what it contains — which is why the message reads as freshness.
          #
          # So this is not a retry around flakiness; it is the wait that a
          # single update does not perform. A pin naming a version that was
          # never published still fails, after the last attempt, and says which
          # of the two situations it is.
          for attempt in 1 2 3 4 5 6; do
            xlings update > /dev/null 2>&1 || true
            if # ⚠️ THE PIN MAY NAME THE RELEASE THIS RUN IS VALIDATING, which does
          # not exist yet — that is the whole point of MCPP_SOURCE_REF. Bootstrap
          # from whatever the index has; the step below replaces it with the
          # build under review, and the pin is what an ordinary run tests.
          if [ -n "${MCPP_SOURCE_REF:-}" ]; then
            xlings install mcpp -y -g
          else
            xlings install "mcpp@$MCPP_VERSION" -y -g
          fi; then break; fi
            if [ "$attempt" = 6 ]; then
              echo "::error::mcpp@$MCPP_VERSION never appeared in the index (6 attempts over 5 minutes). If it was just released, the pointer has not propagated; if the pin names a version that was never published, it never will."
              exit 1
            fi
            echo "the index has not caught up yet (attempt $attempt of 6); waiting 60s"
            sleep 60
          done
          mcpp --version
          mcpp self config --mirror GLOBAL
          # ⭐⭐ CROSS-VALIDATION: BUILD THE mcpp UNDER REVIEW AND USE THAT ONE.
          #
          # Empty in the ordinary run, so this job keeps testing the RELEASED
          # mcpp the pin above names. Set it — `workflow_dispatch` input, or the
          # repository variable — and the same job runs against that source.
          #
          # ⚠️ THIS EXISTS BECAUSE THE ORDER USED TO BE WRONG. Several mcpp
          # releases went out green and only then turned this ecosystem red: the
          # engine's own CI cannot see a defect that appears only in a real
          # dependency graph, and this repository could not see the engine until
          # it had been published. Validating before the release closes that gap.
          #
          # The released mcpp installed just above is the bootstrap that compiles
          # it; mcpp builds itself and there is no other compiler for it here.
          if [ -n "${MCPP_SOURCE_REF:-}" ]; then
            src="$RUNNER_TEMP/mcpp-src"
            [ -d "$src" ] || git clone --quiet --depth 1 \
              --branch "$MCPP_SOURCE_REF" \
              https://github.com/mcpp-community/mcpp.git "$src"
            # ⚠️ THE CLONE'S OWN WORKSPACE PIN MUST NOT DECIDE WHICH mcpp
            # BUILDS IT. `.xlings.json` at mcpp's root pins the mcpp that
            # compiles mcpp, and that pin does not move when mcpp is released —
            # so a build inside the checkout obeys it and tries to install a
            # version the index may no longer carry:
            #
            #     [error] xlings: version '2026.8.17.1' not found for 'mcpp'
            #       available: 2026.8.25.1
            #
            # What is wanted here is the source compiled by the mcpp installed
            # above, which is exactly what removing the file leaves.
            rm -f "$src/.xlings.json"
            ( cd "$src" && mcpp build --release )
            # ⭐ `$src` is a FRESH clone each run, so `target/` holds exactly what
            # this step just built and there is no earlier fingerprint directory
            # to pick by mistake. `-printf` would be the safer form on a cached
            # tree and is a GNU extension this must not use — one of the runners
            # that reaches this line is macOS.
            built=$(find "$src/target" -type f -name mcpp -perm -u+x | head -1)
            [ -n "$built" ] || { echo "::error::mcpp did not build from $MCPP_SOURCE_REF"; exit 1; }
            echo "$(cd "$(dirname "$built")" && pwd)" >> "$GITHUB_PATH"
            # ⚠️ Reported, because a PATH entry that does not win looks exactly
            # like one that does until something built with the wrong engine.
            echo "under review: $("$built" --version)  (from $MCPP_SOURCE_REF)"
          fi

      - name: The backend cross-builds
        run: |
          # ⚠️ TWICE, AND THE FIRST IS ALLOWED TO FAIL — every row of this
          # matrix is a machine that has never targeted this triple, which is
          # precisely where mcpp's lazy install of the target C library shows.
          # The first build compiles sources needing its headers before they
          # exist; the second has them. A single build here reported a
          # portability failure that was really a cold-machine one.
          mcpp build --target riscv64-none-elf || true
          mcpp build --target riscv64-none-elf