SCRYDOSBox-XReferenceSessionbuild_check

DOSBox-XSession

build_check

Check which DOSBox-X would run and whether it has the debugger a session needs, before starting one.

build_check(binary="")

Try it

On any host where DOSBox-X is installed, before a session is open. It needs no program.
Ask

Which DOSBox-X would you run, and does it have the debugger?

Call
build_check()
Reply 3 of 9 fields
{
  "status": "ok",
  "debugger": true,
  "heavy_debug": true
}

The build has the debugger, and it has heavy debugging, the option trace needs.

The whole reply
JSON
{
  "summary": "<volatile>",
  "status": "ok",
  "binary": "<volatile>",
  "binary_origin": "<volatile>",
  "version": "<volatile>",
  "debugger": true,
  "heavy_debug": true,
  "debugger_commands": ["RUNSTATE", "STEPIN", "SAVESTATE", "LOADSTATE", "PRESENCE", "VGAMEMDUMP", "... 8 more"],
  "tools": ["a20", "audio_compare", "audio_record", "breakpoint_at", "breakpoint_interrupt", "build_check", "... 56 more"]
}

Arguments

binary string, default ""
The DOSBox-X to check, as an absolute path. Left empty, DOSBOX_X_BINARY, else the dosbox-x on the PATH.

What comes back

binary
The executable that was found.
binary_origin
Where its path came from: argument, DOSBOX_X_BINARY or PATH.
version
The build's own version line, or available: false with a why: a version that cannot be read never fails the call.
heavy_debug
Whether the build has heavy debugging, which trace and a freeze watch, one that holds bytes at their value, need. false is an answer, not a failure.
debugger_commands
The optional debugger commands the build has; several tools need one. Left out when it has none.
debugger_commands_missing
Each command the build lacks (command) with the tools that stop working without it (disables). Left out when none is missing.
All 8 reply fields
  • binary (string)
  • binary_origin (string)
  • debugger (boolean)
  • debugger_commands (array)
  • debugger_commands_missing (array)
  • heavy_debug (boolean)
  • tools (array)
  • version (string or object)

What it refuses

Why it works this way

A DOSBox-X built without the debugger starts fine and then leaves start waiting until it gives up, so this check comes first. It reads the binary's own bytes and never asks it: -helpdebug lists -break-start on a build without the debugger too, and on Windows it prints nowhere and never exits.

It is refused while a session is open: reading the version starts a second emulator, which a build that does not know the option runs until the check gives up. The answer is about the build, never about a reading, and debugger is always true: a build without one is refused.

More on why

tools lists this server's tools by name.

The contract your client receives
Text
Whether a DOSBox-X binary resolves and carries the debugger. Run before `start`; it
refuses `session_live` while a session is live. `binary`: omitted, `DOSBOX_X_BINARY`, else
the PATH's `dosbox-x`; a named build that fails is refused.

Reply: `binary`, `binary_origin`, `version`, `debugger`, `heavy_debug` (`trace` and a freeze
watch need it), `debugger_commands` (which of `RUNSTATE`, `STEPIN`, `SAVESTATE`, `LOADSTATE`, `PRESENCE`, `VGAMEMDUMP`, `BPIF`, `CAPTURE`, `TAP`, `PORTINFO`, `DOSTRACE`, `PIC`, `A20`, `MEMDUMPLIN` the build's debugger has;
omitted when none), `debugger_commands_missing` (each one it lacks, with the tools that
command disables; omitted when none is missing).
Tools