Repository navigation
Building and running
Cross-compiled from macOS or Linux to 32-bit Windows XP. There is no other valid target: V86 mode exists only in 32-bit mode, so this is permanently i686.
brew install mingw-w64 cmake # or your distro's equivalent
./scripts/build.sh # configure + build
./scripts/build.sh clean # from scratchProduces:
| Binary | What it is |
|---|---|
build/ntvdmhost.exe |
The VDM host. This is the one that matters. |
build/ntvdmex.exe |
A small separate launcher/shell preview. |
build/rigshot.exe |
Desktop capture + remote poking for the test box (scripts/build-rigshot.sh). |
build/controld.exe |
The rig's control daemon (scripts/build-controld.sh). |
⚠️ Deploying the wrong one of the first two has cost real sessions. If you deploy the launcher it becomes the IFEO debugger forntvdm.exeand relaunches into itself — and runs still appear to "succeed" because the harness copies a stale log. The only tell is that two different targets produce the same md5. Checksum what you deploy.
It links with no C runtime at all (-nostdlib -nostartfiles), and src/runtime.c
supplies the entry point and mem* primitives.
This is not minimalism for its own sake: the mingw-w64 toolchain is UCRT-default, and
UCRT (api-ms-win-crt-*.dll) does not exist on Windows XP. A CRT-linked binary simply will
not load there. The PE subsystem and OS version fields are pinned to 5.01 for the same
reason.
./scripts/check-imports.sh # asserts every import is an XP-shipped DLLTwo consequences worth knowing:
- No
printf, nostrlen, nomalloc. Use thezput/zhexhelpers insrc/host/log.handwsprintfAfrom user32. -
GCC will turn a hand-rolled
strlenloop into a call tostrlenunless you pass-ffreestanding -fno-builtin. It will do the same formemset. This is why those flags appear in every build script here.
./tools/dostest/run.shIt builds and runs 18 batteries — 664 checks, about ten seconds — against the real
src/dos/ and src/vdd/ code, and exits non-zero if anything fails, so it can gate a
commit. This is the development loop; see Testing and oracles.
The battery binaries are gitignored (
tools/dostest/*_test) because tracking them means binary churn in every commit.run.shcompiles them each time — so a fresh clone has no*_testfiles and running them directly finds nothing. Always go throughrun.sh.
NTVDMEX becomes the machine's VDM through an Image File Execution Options Debugger
value on ntvdm.exe:
copy ntvdmhost.exe C:\ntvdmex\
reg add "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ntvdm.exe" ^
/v Debugger /t REG_SZ /d "C:\ntvdmex\ntvdmhost.exe" /fTo put the machine back exactly as it was:
reg delete "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ntvdm.exe" ^
/v Debugger /fThen launch any DOS program. C:\ntvdmex\target.txt overrides what gets run, which is how
the test harness drives it without depending on shell integration.
-
Win16 programs will break. 16-bit Windows programs launch through
ntvdm.exetoo, and NTVDMEX has no WOW layer at all. Until #129 (passthrough) lands, this key should be treated as a test-rig setting, not a daily driver. -
Console behaviour differs. DOS output is buffered and flushed to
CONOUT$at exit, so redirection and piping fromcmd.exeare bypassed and every DOS program pops a window (#131). -
If the host will not start, every DOS and Win16 launch on the machine is broken and the
fix is the
reg deleteabove. Know that before you need it (#132). -
With the key absent, everything silently runs under stock
ntvdmand still "works". More than one session has gone into debugging code that was never executed. If a result surprises you, check the key first.
Settings live in HKCU\Software\NTVDMEX, edited from File → Settings… (six tabs:
General, CPU, Display, Audio, Input, Drives).
Precedence is:
built-in default < registry < text file on the test share
The text files win on purpose — the headless rig configures the host by writing files and re-launching it, and a setting clicked in a dialog must never silently change what a measurement is measuring. See Motivations and decisions.
⚠️ 40 of the 46 settings are stored and honoured by nothing — they came from the old menu scaffold.settings_apply()insrc/host/main.cis the honest list of the ones the emulator actually consults (#136).
Understand it
Work on it
- Building and running
- Testing and oracles
- The bare-metal rig
- Provisioning a new rig
⚠️ Traps and lessons
Live state
- STATE.md — where we are
- Issues — what's left
- Session archive
Published from docs/wiki/.
Edit there, not here — tools/wiki/publish.sh overwrites this wiki.