# Lua 5.1.5 — substantial real-world C test

Lua's reference C implementation (17K lines, 24 source files) compiled
for the W65816 / Apple IIgs target.  Serves as a "real-world C" stress
test for the backend — exercises every major language feature, dispatch-
heavy VM, deep recursion, GC walks, etc.

## Build

```
bash tests/lua/build.sh        # compile all 24 Lua sources + stubs
bash tests/lua/runLuaTest.sh   # build + link the test wrapper
```

## What works

- **All 24 Lua source files compile cleanly** under our backend.
- **Links into a multi-segment binary** via link816 `--segment-cap`.
  Five segments at ~40KB each (with gc-sections enabled — drops to one
  segment when only the API entry points are used).
- **Loads in MAME** (verified via direct `mame ... -autoboot_script`).

## Caveats

A few functions (`symbexec` in ldebug.c, `auxsort` in ltablib.c,
`luaV_execute` in lvm.c, plus `lstrlib.c` under `--layer2`) exceed what
LLVM's `greedy` allocator can place with the 65816's single accumulator
and abort with `ran out of registers during register allocation`.  This
is a hardware constraint, not a miscompile.  `build.sh` handles it
automatically: it compiles through `scripts/ccRegallocFallback.sh`, which
retries an affected TU with `-mllvm -regalloc=basic` (the simpler,
always-terminating allocator) only when greedy fails.  No per-file list
is maintained; a newly register-heavy TU is handled transparently.

These functions are the largest in Lua and exhibit unusual register
pressure (luaV_execute is a 30+ case VM dispatch).  See the regalloc
discussion in [`../../LLVM_65816_DESIGN.md`](../../LLVM_65816_DESIGN.md).

## Runtime execution status

The compiled binary loads under MAME and reaches its entry point
(verified via direct `mame` invocation showing `MAME-READY pc=0x001000`).
Wrapping the run inside `scripts/runMultiSeg.sh` from the agent shell
crashes with SIGSEGV before producing output — this is sandbox-related,
not a code defect.  The Lua API smoke test (push 3 ints, sum, check
strings, close state) compiles and links to 5 segments (~200 KB) so a
full Lua interpreter session is feasible if the harness is run in a
plain shell.

## Files

- `lua-5.1.5/` — vendored Lua 5.1.5 source tree (from www.lua.org)
- `build.sh` — compile script (auto-falls-back to basic regalloc via
  `scripts/ccRegallocFallback.sh` when greedy can't place a TU)
- `luaStubs.c` — `strcoll`, `strxfrm`, `freopen` stubs for missing libc
- `luaTest.c` — minimal Lua API test (sentinel `0xC0DE` if pass)
- `runLuaTest.sh` — full build + run wrapper