Repro workflow

Emulator Workflows

Pick the shortest emulator path that answers the question: QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs. for automated proof, 86Box86BoxA PC emulator used here as a period-hardware comparison target when QEMU behavior looks suspicious. for hardware-flavored comparison, real DOSreal DOSA comparison run using MS-DOS, PC DOS, or FreeDOS instead of LainDOS to separate guest bugs from emulator bugs. in QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs. to split blame, and BochsBochsA debugger-friendly x86 emulator useful as a third opinion when QEMU and 86Box disagree. when you need debugger-grade CPU inspection.

Decision rules

QEMU first
default

Use QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs. for fast scripted tests, serial logs, monitor socketsmonitor socketA QEMU control channel used to send keys, capture screenshots, inspect registers, or quit scripted runs., VNCVNCA remote framebuffer protocol QEMU can expose so tests and humans can inspect graphical output headlessly. screenshots, and normal game smokesmoke testA coarse end-to-end run that proves a game or workflow reaches a visible expected state without fatal markers. runs. The repo picks LAINDOS_QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs. first, then the sibling patched QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs. build, then qemuQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs.-system-i386 from PATH.

noteQEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs._VGAVGAThe PC video standard LainDOS and the demos use for text and graphics output. defaults to std,retrace=precise for game runs.
noteUse -serial stdio or a log file when tests need grep-able output.
noteAttach -device sb16 for generic Sound Blaster runs; add -device adlib only for games that need OPLAdLibThe classic Yamaha OPL FM-synthesis sound path. QEMU exposes it with -device adlib, separately from -device sb16; attach it only for games that need that probe path./AdLibAdLibThe classic Yamaha OPL FM-synthesis sound path. QEMU exposes it with -device adlib, separately from -device sb16; attach it only for games that need that probe path. probing.
86Box compare
hardware flavor

Use 86Box86BoxA PC emulator used here as a period-hardware comparison target when QEMU behavior looks suspicious. when QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs. looks suspicious or when a game wants period hardware. Keep experiments in copies of build/86box-serial-file/ so the baseline VM profile stays stable.

noteAscendancy currently likes gfxcard = s3_trio64_pci.
noteTry cpu_use_dynarec = 0 and fpu_softfloat = 1 as comparison toggles.
noteIf 86Box86BoxA PC emulator used here as a period-hardware comparison target when QEMU behavior looks suspicious. progresses and QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs. stalls, suspect emulator behavior before changing LainDOS.
Real DOS in QEMU
blame splitter

Boot a real DOSreal DOSA comparison run using MS-DOS, PC DOS, or FreeDOS instead of LainDOS to separate guest bugs from emulator bugs. floppy in QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs. and expose the game tree with QEMU FAT exportQEMU FAT exportQEMU's file=fat:rw drive mode, which exposes a host directory as a DOS FAT drive for quick real-DOS comparisons. when you need to separate a LainDOS bug from a QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs./game/runtime bug.

noteQEMU FAT exportQEMU FAT exportQEMU's file=fat:rw drive mode, which exposes a host directory as a DOS FAT drive for quick real-DOS comparisons. needs an absolute host path.
noteIf real DOSreal DOSA comparison run using MS-DOS, PC DOS, or FreeDOS instead of LainDOS to separate guest bugs from emulator bugs. in QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs. reproduces the problem, de-prioritize LainDOS DOS/filesystem debugging.
noteLoad MOUSE.COM in AUTOEXEC.BAT when the comparison needs mouse input.
Bochs or v86
specialized

Use BochsBochsA debugger-friendly x86 emulator useful as a third opinion when QEMU and 86Box disagree. for short debugger-heavy reproductions when QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs. and 86Box86BoxA PC emulator used here as a period-hardware comparison target when QEMU behavior looks suspicious. disagree. Use v86v86A browser-hosted x86 emulator used by the site to boot the small LainDOS demo image. for the browser demo and docs smoke, not as the authoritative compatibility target.

noteBochsBochsA debugger-friendly x86 emulator useful as a third opinion when QEMU and 86Box disagree. is best for CPU inspection, not broad regression sweeps.
noteThe site pins v86v86A browser-hosted x86 emulator used by the site to boot the small LainDOS demo image. and uses the matching bochsBochsA debugger-friendly x86 emulator useful as a third opinion when QEMU and 86Box disagree.-vgabios.bin from the v86v86A browser-hosted x86 emulator used by the site to boot the small LainDOS demo image. BIOSBIOSFirmware services available before DOS exists; it loads the boot sector and provides interrupts such as INT 13h disk I/O. tree.
noteBrowser v86v86A browser-hosted x86 emulator used by the site to boot the small LainDOS demo image. is intentionally a small demo path around shell_monkey.img.

Which command proves what?

The source-of-truth commands stay in the Makefile and docs/emulator_workflows.md; this table is the quick selector.

Boot and DOS API regressions
Serial PASS:/FAIL: markers and HALT.
QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs. headless
make test
Interactive shell demo
Rebuilds shell_monkey.img, copies it into the site, and keeps the browser image current.
v86v86A browser-hosted x86 emulator used by the site to boot the small LainDOS demo image. or QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs.
make site
Monkey Island demo
Shell launch, game startup, and framebufferframebufferThe raw pixels currently shown by VGA; smoke tests hash or inspect it when serial output cannot prove gameplay. activity.
QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs. + SB16SB16Sound Blaster 16 audio hardware. QEMU exposes the DSP path with -device sb16; some games also need the separate -device adlib OPL path.
make test-monkey-demo
Full game ladder
Monkey, Wolf3D, and Ascendancy when local media exists.
QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs.
make test-game-smokes
Wolfenstein 3D
Uses precise retraceretraceThe VGA vertical-blank signal that many games poll through port 0x3DA for timing. and the separate AdLibAdLibThe classic Yamaha OPL FM-synthesis sound path. QEMU exposes it with -device adlib, separately from -device sb16; attach it only for games that need that probe path. device so startup probes match 86Box86BoxA PC emulator used here as a period-hardware comparison target when QEMU behavior looks suspicious..
QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs. VGA retraceretraceThe VGA vertical-blank signal that many games poll through port 0x3DA for timing. + SB16SB16Sound Blaster 16 audio hardware. QEMU exposes the DSP path with -device sb16; some games also need the separate -device adlib OPL path./AdLibAdLibThe classic Yamaha OPL FM-synthesis sound path. QEMU exposes it with -device adlib, separately from -device sb16; attach it only for games that need that probe path.
make test-wolf3d-smoke
Ascendancy
Use the local SAHFSAHFAn x86 instruction that loads status flags from AH; Ascendancy exposed a QEMU TCG parity-flag bug here.-fixed QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs. before treating a stall as LainDOS.
patched QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs., then 86Box86BoxA PC emulator used here as a period-hardware comparison target when QEMU behavior looks suspicious.
make test-ascendancy-smoke
Shortline
Uses -icount pacing for the game's PITPITThe Programmable Interval Timer that drives the classic PC timer tick and many game timing loops. calibration.
paced QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs.
make test-shortline-smoke
Norton Commander
Checks launcher-style EXEC and display startup.
QEMUQEMUThe default fast emulator for automated LainDOS builds, tests, monitor probes, and game smoke runs.
make test-norton-commander-smoke

Probe before waiting

When a game appears stuck, capture a small discriminator first. The right serial logserial logCaptured COM1 text output, used by tests to detect PASS, FAIL, exceptions, and unhandled DOS calls., monitor socketmonitor socketA QEMU control channel used to send keys, capture screenshots, inspect registers, or quit scripted runs. probe, or framebufferframebufferThe raw pixels currently shown by VGA; smoke tests hash or inspect it when serial output cannot prove gameplay. hash can save hours of guessing.

serial
Keep COM1COM1The first PC serial port. LainDOS uses it as the primary machine-readable debug log. output in stdio or a log so tests can reject EXC, FAIL:, and unhandled INT 21hINT 21hThe main DOS API interrupt. Programs select services such as open, read, EXEC, and exit with AH. markers.
monitor
Use a monitor socketmonitor socketA QEMU control channel used to send keys, capture screenshots, inspect registers, or quit scripted runs. for sendkey, screendump, info registers, x /12i $eip, and xp /1dw 0x46c.
framebuffer
Hash or inspect screenshots when serial output cannot prove the game reached visible gameplay.
CPU sample
Sample registers and a few instructions before waiting minutes; a DOS trace may only show the last visible boundary.