Updating for use with JoeyLib installer.

docs/INSTALL.md

@@ -21,7 +21,6 @@ After install, the `llvm816/` directory tree contains everything:
 |---|---:|---|
 | `tools/llvm-mos/` | 5.0 GB | LLVM source tree (clone of llvm-mos).  Our backend source is *symlinked* into here at build time. |
 | `tools/llvm-mos-build/` | 1.4 GB | Compiled clang/llc/llvm-mc binaries.  This is where you actually run the compiler from. |
-| `tools/llvm-mos-sdk/` | 400 MB | Prebuilt llvm-mos SDK (the original 6502 distribution).  Mostly unused by us; kept as a reference baseline. |
 | `tools/calypsi/` | 580 MB | Commercial Calypsi 5.16 65816 C compiler — installed for output-quality comparisons in `compare/`. |
 | `tools/nlist/` | 68 KB | Dave Lyons' NiftyList toolbox catalog (`NList.Data.txt`).  Source of truth for the IIgs toolbox bindings auto-generated into `runtime/include/iigs/toolbox.h`. |
 | `tools/gsos/` | 13 MB | Apple GS/OS 6.0.2 / 6.0.4 disk images for booting under MAME. |
@@ -101,7 +100,7 @@ That's it.  `setup.sh` runs five stages in order:
 | Stage | Script | What it does | Time |
 |---|---|---|---|
 | 1/5 | `installDeps.sh` | `sudo apt-get install` the packages listed above. | ~1 min |
-| 2/5 | `installLlvmMos.sh` | Clone `llvm-mos` source (5 GB), download prebuilt llvm-mos SDK (400 MB), **apply our W65816 backend** (symlinks + patches), **build clang/llc/llvm-mc with W65816 target enabled**, **build `link816` + `omfEmit`**, and **build the runtime libraries** (`libc.o`, `crt0.o`, `libgcc.o`, soft-float, etc.).  After this stage you have a working W65816 toolchain end-to-end. | ~30-60 min (first time; LLVM build is the long pole) |
+| 2/5 | `installLlvmMos.sh` | Clone `llvm-mos` source (5 GB) at the commit pinned in `llvmMosCommit.txt`, **apply our W65816 backend** (symlinks + patches), **build clang/llc/llvm-mc/llvm-ar with W65816 target enabled**, **build `link816` + `omfEmit`**, and **build the runtime libraries** (`libc.o`, `crt0.o`, `libgcc.o`, soft-float, etc.).  After this stage you have a working W65816 toolchain end-to-end. | ~30-60 min (first time; LLVM build is the long pole) |
 | 3/5 | `installMame.sh` | Install MAME via apt, download `apple2gs.zip` (ROM 03) and `apple2gsr1.zip` (ROM 01) into `tools/mame/roms/`. | ~30 s |
 | 4/5 | `installCalypsi.sh` | Download Calypsi 5.16 .deb, extract its payload into `tools/calypsi/` (no system-wide install). | ~30 s |
 | 5/5 | `installGno.sh` | Fetch GNO/ME 2.0.6 + GS/OS 6.0.4 disk images for shell-command testing under MAME. | ~30 s |
@@ -176,7 +175,6 @@ llvm816/                            ← your repo checkout
     │       ├── llvm-mc                 ← standalone assembler
     │       ├── llvm-objdump            ← disassembler
     │       └── ...                     (FileCheck, llvm-readobj, opt, etc.)
-    ├── llvm-mos-sdk/                   (400 MB) — prebuilt llvm-mos SDK
     ├── link816                         (~120 KB) — OUR LINKER ⭐
     ├── omfEmit                         (~70 KB) — OMF v2.1 emitter for GS/OS Loader
     ├── cadius/                         — Apple ProDOS / GS/OS disk image tool
@@ -235,8 +233,7 @@ LLVM clone).
 
 ```bash
 bash scripts/installDeps.sh           # apt packages
-bash scripts/installLlvmMos.sh        # llvm-mos clone + prebuilt SDK
+bash scripts/installLlvmMos.sh        # pinned llvm-mos clone + clang/llc build + link816 + runtime
-bash scripts/installLlvmMos.sh --build  # also build clang/llc (slow)
 bash scripts/installMame.sh           # MAME + apple2gs ROMs
 bash scripts/installCalypsi.sh        # reference compiler (optional)
 bash scripts/verify.sh                # sanity-check everything
@@ -248,8 +245,8 @@ If you only want to *build* C programs (no benchmarks, no comparisons),
 ### Building W65816 clang from source
 
 `setup.sh` always builds clang from source — that's the only way to
-get a `clang` that actually targets W65816 (the prebuilt llvm-mos SDK
+get a `clang` that actually targets W65816 (a stock llvm-mos release
-in `tools/llvm-mos-sdk/` only knows about the 6502 MOS target).  The
+only knows about the 6502 MOS target).  The
 initial build takes 30-60 minutes depending on core count; after that
 incremental rebuilds are ~30 seconds:
 
@@ -368,9 +365,9 @@ causes:
    ninja -C tools/llvm-mos-build llc clang
    ```
 
-3. You're using the prebuilt SDK (`tools/llvm-mos-sdk/bin/...`).  That's
+3. You're using a stock llvm-mos clang (for example a `tools/llvm-mos-sdk/`
-   the original llvm-mos SDK; our W65816 target lives only in our
+   left by an older install, or a system llvm-mos).  Our W65816 target
-   *source build* at `tools/llvm-mos-build/bin/`.
+   lives only in our *source build* at `tools/llvm-mos-build/bin/`.
 
 ### `linkage error: missing __umulhisi3` / `missing __mulsi3` / similar
 
@@ -403,18 +400,19 @@ flags.
 
 ### `git: refusing to fetch into ...` for llvm-mos
 
-`installLlvmMos.sh` refuses to refresh the LLVM clone if it has local
+The llvm-mos clone is pinned to the commit in `llvmMosCommit.txt`.
-modifications or is on a non-`main` branch — because our backend
+`installLlvmMos.sh` only ever moves the clone to that pin (unapplying our
-symlinks are stitched into the clone and a destructive refresh would
+backend first), and refuses if the clone is on a non-`main` branch or has
-stomp them.
+changes other than our backend.
 
-If you really want to refresh from upstream:
+To move to the latest upstream:
 
 ```bash
 bash scripts/updateLlvmMos.sh
 ```
 
-That script handles the symlinks safely.
+That script handles the symlinks safely and rewrites `llvmMosCommit.txt`.
+Rebuild, run the W65816 tests, then commit the pin file.
 
 ### Disk fills up during the LLVM build
 

docs/USAGE.md

@@ -62,7 +62,6 @@ llvm816/                            ← repo root; everything is contained here
 │   │       ├── llvm-mc             ← standalone assembler
 │   │       ├── llvm-objdump        ← disassembler
 │   │       └── ...
-│   ├── llvm-mos-sdk/               ← prebuilt llvm-mos SDK (~400 MB, mostly unused)
 │   ├── link816                     ← OUR LINKER (single binary, ~120 KB)
 │   ├── omfEmit                     ← turns flat binary → Apple IIgs OMF v2.1
 │   ├── mame/                       ← Apple IIgs ROMs for MAME

llvmMosCommit.txt

@@ -0,0 +1 @@
+c798c31416f72b395c658b5502d281a162387ab1

scripts/applyBackend.sh

@@ -13,7 +13,6 @@
 set -euo pipefail
 source "$(dirname "$0")/common.sh"
 
-LLVM_SRC="$TOOLS_DIR/llvm-mos"
 SRC_TREE="$PROJECT_ROOT/src"
 PATCH_DIR="$PROJECT_ROOT/patches"
 

scripts/common.sh

@@ -6,6 +6,15 @@ PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 TOOLS_DIR="$PROJECT_ROOT/tools"
 DOWNLOAD_CACHE="$PROJECT_ROOT/.cache/downloads"
 
+# The llvm-mos clone our backend is stitched into, and its build tree.
+# The clone is pinned to the commit in llvmMosCommit.txt so a fresh
+# install builds exactly what we last tested; updateLlvmMos.sh moves the
+# pin forward.
+LLVM_SRC="$TOOLS_DIR/llvm-mos"
+LLVM_BUILD="$TOOLS_DIR/llvm-mos-build"
+LLVM_MOS_URL="https://github.com/llvm-mos/llvm-mos.git"
+LLVM_MOS_COMMIT_FILE="$PROJECT_ROOT/llvmMosCommit.txt"
+
 install -d "$TOOLS_DIR" "$DOWNLOAD_CACHE"
 
 log() {
@@ -44,6 +53,52 @@ haveCmd() {
     command -v "$1" >/dev/null 2>&1
 }
 
+# Print the llvm-mos commit this tree is pinned to.
+llvmMosPinnedCommit() {
+    local commit
+    [ -s "$LLVM_MOS_COMMIT_FILE" ] || die "missing pin file: $LLVM_MOS_COMMIT_FILE"
+    commit="$(tr -d '[:space:]' < "$LLVM_MOS_COMMIT_FILE")"
+    [[ "$commit" =~ ^[0-9a-f]{40}$ ]] || die "bad commit in $LLVM_MOS_COMMIT_FILE: '$commit'"
+    printf '%s\n' "$commit"
+}
+
+# Shallow-fetch $1 (a commit SHA) and check it out as local branch main.
+# The clone must already have its backend unapplied (unapplyBackend).
+checkoutLlvmMosCommit() {
+    local commit="$1"
+    git -C "$LLVM_SRC" fetch --depth=1 origin "$commit"
+    git -C "$LLVM_SRC" checkout -q -B main FETCH_HEAD
+}
+
+# Undo applyBackend.sh so the clone is a pristine upstream tree again:
+# reverse our patches, then delete the symlinks into src/.  Dies if the
+# clone still has changes afterwards (someone edited it by hand).
+unapplyBackend() {
+    local patch
+    local link
+    local target
+    log "reverting any applied patches"
+    for patch in "$PROJECT_ROOT"/patches/*.patch; do
+        [ -f "$patch" ] || continue
+        if git -C "$LLVM_SRC" apply --reverse --check "$patch" >/dev/null 2>&1; then
+            git -C "$LLVM_SRC" apply --reverse "$patch"
+            log "  reverted: $(basename "$patch")"
+        fi
+    done
+    # Symlinks from applyBackend.sh are untracked files inside tracked
+    # directories; git leaves them alone, so remove them explicitly.
+    log "removing symlinks under $LLVM_SRC pointing into $PROJECT_ROOT/src"
+    find "$LLVM_SRC" -type l | while read -r link; do
+        target="$(readlink -f "$link" || true)"
+        case "$target" in
+            "$PROJECT_ROOT"/src/*) rm "$link" ;;
+        esac
+    done
+    if ! git -C "$LLVM_SRC" diff --quiet || ! git -C "$LLVM_SRC" diff --cached --quiet; then
+        die "llvm-mos checkout still has local changes after cleanup. Inspect with: git -C $LLVM_SRC status"
+    fi
+}
+
 # runGnoMameSmoke <omf-path> <marker1> [<marker2> ...]
 #
 # Launch an already-built GNO/ME OMF under real GS/OS 6.0.4 + GNO in

scripts/installLlvmMos.sh

@@ -1,11 +1,10 @@
 #!/usr/bin/env bash
 # Install + build the W65816 toolchain on top of llvm-mos:
-#   1. Clone llvm-mos source.
+#   1. Clone llvm-mos source at the commit pinned in llvmMosCommit.txt.
-#   2. Download the prebuilt llvm-mos-sdk (reference baseline).
+#   2. Apply our W65816 backend INTO the clone (symlinks + patches).
-#   3. Apply our W65816 backend INTO the clone (symlinks + patches).
+#   3. Configure + build clang + llc + llvm-mc + llvm-ar with the W65816 target.
-#   4. Configure + build clang + llc + llvm-mc with the W65816 target.
+#   4. Build link816 + omfEmit (the linker).
-#   5. Build link816 + omfEmit (the linker).
+#   5. Build the runtime (libc.o, crt0.o, libgcc.o, etc.).
-#   6. Build the runtime (libc.o, crt0.o, libgcc.o, etc.).
 #
 # Flags:
 #   --build   (no-op; retained for backward compat — we always build)
@@ -15,76 +14,54 @@ source "$(dirname "$0")/common.sh"
 
 for arg in "$@"; do
     case "$arg" in
-        --build) ;;  # no-op; we always build now (see step 4)
+        --build) ;;  # no-op; we always build now (see step 3)
         *) die "unknown flag: $arg" ;;
     esac
 done
 
-LLVM_SRC="$TOOLS_DIR/llvm-mos"
+# 1. Source tree for backend development, at the pinned commit.
-LLVM_BUILD="$TOOLS_DIR/llvm-mos-build"
-LLVM_SDK="$TOOLS_DIR/llvm-mos-sdk"
-SDK_URL="https://github.com/llvm-mos/llvm-mos-sdk/releases/latest/download/llvm-mos-linux.tar.xz"
-
-# 1. Source tree for backend development.
 #
 # IMPORTANT: this clone is ephemeral scaffolding, not where we do work. Our
 # own sources live in $PROJECT_ROOT/src/ and $PROJECT_ROOT/patches/ and are
-# stitched into this tree by applyBackend.sh. That means a destructive
+# stitched into this tree by applyBackend.sh.  Moving the clone therefore
-# reset here would stomp applied symlinks/patches — so we refuse to touch
+# unapplies the backend first; a clone with any OTHER local change, or on a
-# the clone if it looks modified. Use updateLlvmMos.sh to refresh safely.
+# branch other than main, is left for a human to sort out.
+pinnedCommit="$(llvmMosPinnedCommit)"
 if [ -d "$LLVM_SRC/.git" ]; then
-    currentBranch="$(git -C "$LLVM_SRC" rev-parse --abbrev-ref HEAD)"
+    currentCommit="$(git -C "$LLVM_SRC" rev-parse HEAD)"
-    if [ "$currentBranch" != "main" ]; then
+    if [ "$currentCommit" = "$pinnedCommit" ]; then
-        warn "llvm-mos clone is on branch '$currentBranch' (not main); leaving untouched"
+        log "llvm-mos source already at pinned commit ${pinnedCommit:0:12}"
-    elif ! git -C "$LLVM_SRC" diff --quiet || ! git -C "$LLVM_SRC" diff --cached --quiet; then
-        warn "llvm-mos clone has local modifications; leaving untouched. Use scripts/updateLlvmMos.sh to refresh."
     else
-        log "llvm-mos source already cloned; fetching and fast-forwarding main"
+        currentBranch="$(git -C "$LLVM_SRC" rev-parse --abbrev-ref HEAD)"
-        git -C "$LLVM_SRC" fetch --depth=1 origin main
+        if [ "$currentBranch" != "main" ]; then
-        git -C "$LLVM_SRC" merge --ff-only FETCH_HEAD || warn "fast-forward failed; leaving clone as-is"
+            die "llvm-mos clone is on branch '$currentBranch', not main; refusing to move it to the pinned commit ${pinnedCommit:0:12}"
+        fi
+        log "llvm-mos source at ${currentCommit:0:12}; moving to pinned ${pinnedCommit:0:12}"
+        unapplyBackend
+        checkoutLlvmMosCommit "$pinnedCommit"
     fi
 else
-    log "cloning llvm-mos (shallow)"
+    log "cloning llvm-mos at pinned commit ${pinnedCommit:0:12} (shallow)"
-    git clone --depth=1 https://github.com/llvm-mos/llvm-mos.git "$LLVM_SRC"
+    git init -q "$LLVM_SRC"
+    git -C "$LLVM_SRC" remote add origin "$LLVM_MOS_URL"
+    checkoutLlvmMosCommit "$pinnedCommit"
 fi
 
-# 2. Prebuilt SDK for testing/reference (smoke tests against the
+# 2. Apply our W65816 backend INTO the clone (symlinks + patches).
-# vanilla 6502 MOS target; mostly unused once you have a W65816
-# build).
-if [ -x "$LLVM_SDK/bin/mos-common-clang" ] || [ -x "$LLVM_SDK/bin/clang" ]; then
-    log "llvm-mos-sdk already extracted"
-else
-    archive="$(fetchCached "$SDK_URL" "llvm-mos-linux.tar.xz")"
-    log "extracting llvm-mos-sdk"
-    install -d "$LLVM_SDK"
-    tar -xJf "$archive" -C "$LLVM_SDK" --strip-components=1
-fi
-
-# 3. Apply our W65816 backend INTO the clone (symlinks + patches).
 # Must run BEFORE cmake configure so the W65816 target dir + cmake
 # patch are present.
 log "applying W65816 backend (symlinks + patches)"
 bash "$(dirname "$0")/applyBackend.sh"
 
-# 4. Configure + build LLVM with W65816 enabled.  We always build —
+# 3. Configure (first time only) + build LLVM with W65816 enabled.  ninja
-# without a built clang the rest of the toolchain (runtime, link816)
+# runs every time: it is a few-second no-op when nothing changed, and it
-# can't produce any usable output.  --build is kept as a no-op flag
+# is what picks up a moved pin or an edited backend source.
-# for backward compat.
 needCmd cmake
 needCmd ninja
-# Existence check covers the full LTO toolchain.  llvm-link / llvm-as /
+if [ -f "$LLVM_BUILD/build.ninja" ]; then
-# llvm-dis / opt are required by scripts/ltoLink.sh (Phase 5.2 of
+    log "llvm-mos build already configured"
-# GAP_CLOSURE_PLAN.md); clang and llc are the always-required core.
-if [ -x "$LLVM_BUILD/bin/clang" ] && \
-   [ -x "$LLVM_BUILD/bin/llc" ] && \
-   [ -x "$LLVM_BUILD/bin/llvm-link" ] && \
-   [ -x "$LLVM_BUILD/bin/llvm-as" ] && \
-   [ -x "$LLVM_BUILD/bin/llvm-dis" ] && \
-   [ -x "$LLVM_BUILD/bin/opt" ] && \
-   "$LLVM_BUILD/bin/llc" --version 2>/dev/null | grep -q "^[[:space:]]*w65816[[:space:]]"; then
-    log "llvm-mos-build/bin/clang already exists and supports w65816 (LTO tools present)"
 else
-    log "configuring llvm-mos build (LLVM + clang + lld; ~5 min after the first cmake)"
+    log "configuring llvm-mos build (LLVM + clang + lld)"
     install -d "$LLVM_BUILD"
     cmake -S "$LLVM_SRC/llvm" -B "$LLVM_BUILD" -G Ninja \
         -DCMAKE_BUILD_TYPE=Release \
@@ -96,31 +73,31 @@ else
         -DLLVM_INCLUDE_TESTS=OFF \
         -DLLVM_INCLUDE_EXAMPLES=OFF \
         -DLLVM_INCLUDE_BENCHMARKS=OFF
-    log "building clang, llc, llvm-mc, llvm-objdump (the tools we actually use)"
-    # LTO chain: llvm-link merges bitcode, opt runs IR-level optimizations
-    # (including the Layer 2 gate from Phase 1.12), llvm-as / llvm-dis
-    # are the .bc <-> .ll round-trip for debugging.  Phase 5.2.
-    ninja -C "$LLVM_BUILD" clang llc llvm-mc llvm-objdump llvm-readobj \
-                          llvm-link llvm-as llvm-dis opt
-    log "llvm build done: $LLVM_BUILD/bin/clang"
 fi
+# LTO chain: llvm-link merges bitcode, opt runs IR-level optimizations
+# (including the Layer 2 gate from Phase 1.12), llvm-as / llvm-dis are the
+# .bc <-> .ll round-trip for debugging.  Phase 5.2.  llvm-ar archives the
+# objects of client libraries (joeylib's libjoey.a).
+log "building clang, llc, llvm-mc, llvm-ar, llvm-objdump + LTO tools (first build ~30-60 min)"
+ninja -C "$LLVM_BUILD" clang llc llvm-mc llvm-ar llvm-objdump llvm-readobj \
+                      llvm-link llvm-as llvm-dis opt
+log "llvm build done: $LLVM_BUILD/bin/clang"
 # Sanity check: llc must list w65816 as a registered target.
 if ! "$LLVM_BUILD/bin/llc" --version 2>/dev/null | grep -q "^[[:space:]]*w65816[[:space:]]"; then
     "$LLVM_BUILD/bin/llc" --version 2>/dev/null | head -20
     warn "llc built but does NOT list w65816 as a target.  Backend symlinks/patches may have failed.  Re-run scripts/applyBackend.sh and ninja -C tools/llvm-mos-build."
 fi
 
-# 5. Build link816 + omfEmit.
+# 4. Build link816 + omfEmit.
 log "building link816 + omfEmit"
 make -C "$PROJECT_ROOT/src/link816" all
 
-# 6. Build the runtime (libc.o, crt0.o, libgcc.o, etc.).
+# 5. Build the runtime (libc.o, crt0.o, libgcc.o, etc.).
 log "building runtime"
 bash "$PROJECT_ROOT/runtime/build.sh"
 
 log "llvm-mos install done"
-log "  source:    $LLVM_SRC"
+log "  source:    $LLVM_SRC (llvm-mos ${pinnedCommit:0:12})"
-log "  sdk:       $LLVM_SDK"
 log "  build:     $LLVM_BUILD"
 log "  clang:     $LLVM_BUILD/bin/clang"
 log "  link816:   $PROJECT_ROOT/tools/link816"

scripts/runInMame.sh

@@ -118,8 +118,10 @@ $LUA_CHECKS
 end)
 EOF
 
-OUT=$(SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy timeout 30 mame apple2gs \
+# MAME and MAME_ROMPATH let a client project (joeylib) supply its own
-    -rompath "$PROJECT_ROOT/tools/mame/roms" \
+# patched MAME and ROM set instead of the ones installMame.sh sets up.
+OUT=$(SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy timeout 30 "${MAME:-mame}" apple2gs \
+    -rompath "${MAME_ROMPATH:-$PROJECT_ROOT/tools/mame/roms}" \
     -plugins -autoboot_script "$LUA_PATH" \
     -video none -sound none -nothrottle -seconds_to_run "$SECS" 2>&1 | grep "^MAME-")
 

scripts/updateLlvmMos.sh

@@ -1,16 +1,14 @@
 #!/usr/bin/env bash
-# Refresh the ephemeral llvm-mos checkout to the latest upstream main,
+# Move the pinned llvm-mos checkout to the latest upstream main, re-apply
-# then re-apply our backend (symlinks + patches).
+# our backend (symlinks + patches), and record the new commit in
+# llvmMosCommit.txt.  Rebuild, run the tests, then commit the pin file.
 #
-# This is the ONLY script that is allowed to destructively reset the
+# This is the ONLY script that is allowed to move the clone to an
-# clone.  installLlvmMos.sh intentionally refuses to do so because a
+# UNPINNED commit.  installLlvmMos.sh only ever moves it to the pin.
-# reset would destroy any applied patches.
 
 set -euo pipefail
 source "$(dirname "$0")/common.sh"
 
-LLVM_SRC="$TOOLS_DIR/llvm-mos"
-
 [ -d "$LLVM_SRC/.git" ] || die "llvm-mos checkout not found; run setup.sh first"
 
 currentBranch="$(git -C "$LLVM_SRC" rev-parse --abbrev-ref HEAD)"
@@ -18,33 +16,7 @@ if [ "$currentBranch" != "main" ]; then
     die "llvm-mos is on branch '$currentBranch', expected main. Refusing to reset."
 fi
 
-# First un-apply our patches so the reset only discards upstream drift,
+unapplyBackend
-# not our work.  Symlinks are unaffected by git reset since untracked
-# directories are left alone (our symlinks live inside tracked dirs but
-# are untracked files themselves).
-log "reverting any applied patches"
-for patch in "$PROJECT_ROOT"/patches/*.patch; do
-    [ -f "$patch" ] || continue
-    if git -C "$LLVM_SRC" apply --reverse --check "$patch" >/dev/null 2>&1; then
-        git -C "$LLVM_SRC" apply --reverse "$patch"
-        log "  reverted: $(basename "$patch")"
-    fi
-done
-
-# Symlinks from applyBackend.sh are untracked files inside tracked
-# directories.  git reset --hard leaves them in place, but we clean
-# them proactively so the fast-forward sees a truly clean tree.
-log "removing symlinks under $LLVM_SRC pointing into $PROJECT_ROOT/src"
-find "$LLVM_SRC" -type l | while read -r link; do
-    target="$(readlink -f "$link" || true)"
-    case "$target" in
-        "$PROJECT_ROOT"/src/*) rm "$link" ;;
-    esac
-done
-
-if ! git -C "$LLVM_SRC" diff --quiet || ! git -C "$LLVM_SRC" diff --cached --quiet; then
-    die "llvm-mos checkout still has local changes after cleanup. Inspect with: git -C $LLVM_SRC status"
-fi
 
 log "fetching and resetting to origin/main"
 git -C "$LLVM_SRC" fetch --depth=1 origin main
@@ -53,4 +25,7 @@ git -C "$LLVM_SRC" reset --hard FETCH_HEAD
 log "re-applying backend"
 "$PROJECT_ROOT/scripts/applyBackend.sh"
 
-log "update complete"
+newCommit="$(git -C "$LLVM_SRC" rev-parse HEAD)"
+printf '%s\n' "$newCommit" > "$LLVM_MOS_COMMIT_FILE"
+log "update complete: pinned llvm-mos to $newCommit"
+log "rebuild (ninja -C $LLVM_BUILD), run the W65816 tests, then commit llvmMosCommit.txt"

scripts/verify.sh

@@ -24,9 +24,10 @@ check "ninja"          ninja --version
 check "clang (host)"   clang --version
 check "git"            git --version
 
-# llvm-mos source + SDK
+# llvm-mos source, at the pinned commit
-check "llvm-mos source tree"   test -d "$TOOLS_DIR/llvm-mos/.git"
+check "llvm-mos source tree"   test -d "$LLVM_SRC/.git"
-check "llvm-mos-sdk extracted" test -x "$TOOLS_DIR/llvm-mos-sdk/bin/mos-common-clang"
+check "llvm-mos at pinned commit ($(llvmMosPinnedCommit | cut -c1-12))" \
+    test "$(git -C "$LLVM_SRC" rev-parse HEAD 2>/dev/null)" = "$(llvmMosPinnedCommit)"
 
 # W65816 backend integration
 check "W65816 source symlinked into llvm-mos" \
@@ -34,6 +35,7 @@ check "W65816 source symlinked into llvm-mos" \
 check "W65816 clang built"          test -x "$TOOLS_DIR/llvm-mos-build/bin/clang"
 check "W65816 llc built"            test -x "$TOOLS_DIR/llvm-mos-build/bin/llc"
 check "W65816 llvm-mc built"        test -x "$TOOLS_DIR/llvm-mos-build/bin/llvm-mc"
+check "llvm-ar built"               test -x "$TOOLS_DIR/llvm-mos-build/bin/llvm-ar"
 check "llc lists w65816 target" \
     bash -c "'$TOOLS_DIR/llvm-mos-build/bin/llc' --version 2>/dev/null | grep -q '^[[:space:]]*w65816[[:space:]]'"
 
@@ -48,11 +50,14 @@ check "runtime/libgcc.o"     test -s "$PROJECT_ROOT/runtime/libgcc.o"
 check "runtime/softFloat.o"  test -s "$PROJECT_ROOT/runtime/softFloat.o"
 check "runtime/softDouble.o" test -s "$PROJECT_ROOT/runtime/softDouble.o"
 
-# MAME + ROMs
+# MAME + ROMs (optional; --skip-mame at install skips this, e.g. when a
-check "mame binary"                 command -v mame
+# client project such as joeylib provides its own MAME).
-check "mame Lua console support"    bash -c "mame -showusage 2>&1 | grep -q -- '-console'"
+if [ -d "$TOOLS_DIR/mame" ]; then
-check "rom: apple2gs.zip"           test -s "$TOOLS_DIR/mame/roms/apple2gs.zip"
+    check "mame binary"                 command -v mame
-check "rom: apple2gsr1.zip"         test -s "$TOOLS_DIR/mame/roms/apple2gsr1.zip"
+    check "mame Lua console support"    bash -c "mame -showusage 2>&1 | grep -q -- '-console'"
+    check "rom: apple2gs.zip"           test -s "$TOOLS_DIR/mame/roms/apple2gs.zip"
+    check "rom: apple2gsr1.zip"         test -s "$TOOLS_DIR/mame/roms/apple2gsr1.zip"
+fi
 
 # Calypsi benchmark (optional; --skip-calypsi at install skips this).
 if [ -d "$TOOLS_DIR/calypsi" ]; then