# dosbox-run

> **Tool `scripts/dosbox-run.sh`** (script, Scripts). Run a DOS program under DOSBox-X from the command line: the whole original game, for ground truth that a single emulated function cannot give (frames, demos, file access, timing).

Run it as `scripts/dosbox-run.sh`. [Source on GitHub](https://github.com/tanepiper/game-frame/blob/main/scripts/dosbox-run.sh).

## Its own help

This is the help text in the tool itself, as `./gameframe tool dosbox-run` prints it.

```text
Run a DOS program under DOSBox-X from the command line: the whole original game, for ground
truth that a single emulated function cannot give (frames, demos, file access, timing).

  scripts/dosbox-run.sh [options] GAME_DIR PROGRAM [ARGS ...]

  --out DIR      logs, the exit code and the copied drive go here (default analysis/dosbox)
  --time N       stop DOSBox-X after N seconds (default 60)
  --window       show the window (default: no window, no sound: SDL dummy drivers)
  --fileio       log every file the program opens, reads, seeks and writes (INT 21h);
                 summarise the log with tools/dos/fileio_trace.py
  --int21        log every INT 21h call
  --debug        start in DOSBox-X's debugger (implies --window; see docs/DOS.md)
  --break        load PROGRAM with DEBUGBOX: it stops at its first instruction in the
                 debugger (with --mcp, a script or agent sets breakpoints, then RUN)
  --mcp PORT     connect the debugger control channel to 127.0.0.1:PORT, where the
                 dosbox-x-mcp-server (agents, port 58991) or tools/dos/dbx_control.py
                 (scripts) listens; start that listener first
  --cycles N     a fixed CPU speed (DOSBox-X "cycles=fixed N"); use one value for every run
  --conf FILE    a DOSBox configuration to start from (repeatable), such as the one a GOG or
                 Steam release ships; this script's own settings come after it and win
                 (window, autoexec, logging). Fullscreen is turned off.
  --set "SECTION KEY=VALUE"   any other DOSBox-X setting (repeatable)
  --in-place     mount GAME_DIR itself (default: a fresh copy in OUT/drive, so saves and
                 settings the program writes never change your copy of the game)
  --then LINE    a DOS command to run after PROGRAM (repeatable), for example to copy a file

It writes RUN_RE.BAT into the mounted drive (removed afterwards; with --in-place that is your
game folder), OUT/dosbox.log (DOSBox-X's log, with the file and INT 21h logs when asked),
OUT/exitcode.txt (the program's exit code, read with IF ERRORLEVEL) and prints the exit code.
Needs dosbox-x (scripts/setup.sh --install). It does not script the debugger, take
screenshots or feed keys: see docs/DOS.md for those.
```

## Named by

Skills: [re-setup](/skills/re-setup), [re-inventory](/skills/re-inventory), [re-format](/skills/re-format), [re-emulate](/skills/re-emulate), [re-verify](/skills/re-verify).