port-and-verify
Use when a byte-matched, exactly linked DOS decompilation with a working modding build is to become a native program for macOS, Linux or Windows that behaves exactly as the original - the portability layer, link stubs, the platform layer, assembly through a static recompiler and then readable C, and verification against DOS by record and replay, golden references and routine fuzzing; with the sound library for Miles AIL 2 games, the null-pointer plan, the host hazard audits (literals written through, null reads, reads past tables and frames) and the black box that records players' sessions.
abedegno · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add abedegno/Exhume --skill port-and-verifyAbout this skill
name: port-and-verify description: Use when a byte-matched, exactly linked DOS decompilation with a working modding build is to become a native program for macOS, Linux or Windows that behaves exactly as the original - the portability layer, link stubs, the platform layer, assembly through a static recompiler and then readable C, and verification against DOS by record and replay, golden references and routine fuzzing; with the sound library for Miles AIL 2 games, the null-pointer plan, the host hazard audits (literals written through, null reads, reads past tables and frames) and the black box that records players' sessions.
Port and verify
Paths are relative to the Exhume checkout. docs/port.md is the method and the reasons; runtime/ is the porting harness every port builds against in place, never copied (runtime/README.md); examples/uw2/ has UW2's configuration, and Underworld Exhumed's uw2/src/port and uw2/src/include have UW2's bindings, the worked example. UW2's port (then UW2Decomp) went from Milestone 1 to Milestone 6a in about 21 hours this way (docs/case-study-uw2.md, "The port").
Before you start
- The modding build works and its layout audit is done (skills/modding-build), and the readability pass has given you the gate (skills/readability-pass): every change to a shared source must pass
tools/gate.py check, so the DOS bytes never change. - One tree, two builds. Port-only C goes in the port's directory, never in a game source; a shared-source change is a macro or type that is the original tokens under Turbo C. Add the port's directory to
[project] exclude. - The runtime is a library. Never copy a runtime file into the project: the tools compile runtime/ where it is (
[port] runtime; docs/port.md, "The runtime"), and the project writes only its bindings and its game's own C. A project with build scripts of its own finds the checkout as Underworld Exhumed's uw2/tools/exhume.py does and pins the Exhume commit it was proved with: best as a git submodule, as Underworld Exhumed does (exhume/), whose recorded commit CI checks out. A fix you find in the runtime goes into Exhume, proved on UW2 (examples/uw2/prove-port.sh) before the project moves its pin.
Steps
- Measure. Write the port's directory's
portgame.hwith at least yourPORT_NAMEandPORT_GAME_MAIN(runtime/README.md, "The project's side"), and ahookgame.hin the shared headers (empty until step 4); includeportable.hfrom a shared header every source includes (the DOS build stages the runtime's beside yours). Fill in[port](docs/config.md) and runtools/portcheck.py: per category, per file, and the names a link still needs. - Compile and link. Fix the errors, then the warnings that matter, each change proved by the gate: near pointers in integers become
NEARPTR; calls get prototypes (OLDSTYLEwhere callers push an int for a char);tools/widths.pyrewrites declarations to explicit widths;tools/layoutcheck.pymust show every file record identical ([port.layout]);tools/intaudit.pylists the promotion sites, and the ones that can leave 16 bits get casts;FAR_COPYandFP_OFFfor the far pointer idioms.tools/portstubs.pywrites link stubs andtools/portbuild.pylinks: the port now runs until the first stub. - Platform and machine. The runtime's platform layer, paragraph map and far heap, EMS memory, VGA, Borland's library, records, crash handler, black box and game finder link as they are; give them what
portgame.hnames (DGROUP,_ctype, the exit chain, the black box:PORT_BLACKBOXand the calls in your main, runtime/README.md; the window's title and icon; what marks the game's folder), and write the C they call:port_load_exeandport_check_exe,port_game_nulls, the port's main and its diagnostics. If the game uses EMS, keep its own EMS entry points overemm_open,emm_mapandemm_close. Load the far data no source defines from the user's own EXE at start-up, by the link's offsets; never ship it. Replace the system assembly (start-up, keyboard, mouse, timer) with C on the platform API. If the game draws its own cursor from relative motion, make the mouse driver steer it to the host's pointer (docs/port.md, "The platform layer": on each host move withabsoluteset, report the motion that puts the game's cursor at the pointer; none while it is still), and offerPlatConfig.mouse_lockfor players who want DOSBox's captured mouse. First exit test: an opening screen whose scan-out equals a DOS screenshot of the same frame, pixel for pixel (hold both builds on it with afor (;;)in a modding build). - Replay. Put a hook on every read of the outside world (
GAME_TIME,KEY,MOUSE,MBUTTONS,JOY_*,WALL_TIME,SRAND,CHECKPOINT), with their original tokens inhookgame.h, writerpgame.hin the shared headers for runtime/replay/replay.c (which the replay DOS build and the port compile where it is), give[replay] linkthe modding link with--add, and fill in[replay].tools/replay.py recorda session in js-dos, replay it twice in DOS (replay.py dos, thencompare --same-build): two DOS runs must agree before the port means anything. If they part, it is stack junk or an unhooked read:UWRPTRACE(or your trace variable) shows the call where they part; give the localSTACK_JUNK(v), with v read fromtools/match.py --dison your own build, and record again. Then replay in the port and compare; mask only what is machinery ([[replay.mask]], with why), and compare far segments as blocks ([replay.segments]). - Assembly. Modules that pass state in registers, patch themselves, discard return addresses or use divide faults as control flow go through
tools/asm2c.py([asm2c] spec and overrides, runtime/port/x86/asmrt with yourasmgame.hin the port's directory and yourasm_divfault; the overrides andasm_divfaultare the game's code, so they live in the project, never in Exhume); commit the output and