Contributing to scry-dosbox-x

This page is for changing the server: where the code lives, which checks a change must pass, and what proves it. What the tools promise is in REFERENCE.md.

Where the code lives

The checks

Shell
$ uv run ruff check .$ uv run mypy --strict .$ uv run mypy --strict --platform win32 .$ uv run pytest -q$ bash .githooks/pre-commit-test.sh

All five pass before a change is committed. What each one proves:

The tests run with a home and a temporary folder of their own, and fail a run that leaves a file in that home (scry-core's private_run). Every file the server writes follows scry-core's rule of file names. tests/conftest.py fails a case whose files break it, except the names the debugger itself picks (MCPDUMP.BIN and the like), which it lists.

On Windows the fourth command is uv run pytest -q --no-cov. The coverage floor is checked on macOS only, because Windows skips the cases that need what it lacks (a FIFO, a mode bit, a symlink).

.github/workflows/ci.yml runs the same checks on GitHub's Linux runners when started by hand, with --no-cov and with jscpd installed for the hook. Without nasm the cases that build the DOS test programs skip, and without ffmpeg the media ones; the workflow installs both.

The committed DOS test programs are built by the nasm major that tests/test_dosbox_x_guest.py names. Their byte-identity cases skip under the older one Ubuntu ships, and run on macOS and Windows.

Running part of the tests

Every pytest run checks the coverage floor, which belongs to the whole repository, so a partial run fails on it. Two traps follow from how addopts is written:

Over ssh on Windows

The server starts DOSBox-X with no window (-set "sdl videodriver=dummy"), so it can be driven over an ssh session on Windows. A venv made with a minor version has its home on a junction that an elevated or ssh session cannot go through (uv trampoline failed to spawn Python child process). Make it with the exact patch version, uv venv -p <patch>.

A scry-core checkout

uv run syncs the environment before its command. So the next plain uv run replaces an editable install of a scry-core checkout (uv pip install -e ../scry-core) with the pinned package. The run then checks the pinned package while looking like a run on the checkout.

Changing a tool

A tool's reply model is its contract:

The tests refuse an ok reply that lacks a required field. tests/test_dosbox_x_reply_models.py refuses a promised field whose condition the sentence does not say.

A change to a tool's arguments, reply model or description changes its reference page. tests/test_dosbox_x_reference_pages.py then fails, naming the tool, the page and the line. Rewrite the pages from the code:

Shell
$ uv run python -m scry_core.reference scry_dosbox_x.server:REFERENCE --write

Every sentence of an entry is in docs/reference/asks.json, one object per tool. It holds what the tool does, its example's ask, a sentence per argument and per field, what it refuses and why. The registry gives the rest.

The examples are calls of the tour, docs/reference/tour/tour.py: one session on Bricks that calls each tool once, with every reply checked.

Shell
$ uv run python docs/reference/tour/tour.py --display 1$ uv run python -m scry_core.reference scry_dosbox_x.server:REFERENCE --write \$     --examples docs/reference/tour/TRANSCRIPT.md demos/*/TRANSCRIPT.md

To replace one of those, add that run's transcript.jsonl to --examples. Each --mark spells one of that computer's directories the way the committed examples do: --mark '/tmp/<the run>=$TMPDIR'.

A tool that moves to another group

An entry is found by its tool's name, so it moves with the tool. Change the tool's group in src/scry_dosbox_x/mcp.py, then rewrite the pages: its block leaves one page and lands on the other.

The line of each group in asks.json, the paragraphs of REFERENCE.md that name the group, and the demos' tables of tools need the same pass. The group of each tool both servers have is roster.SHARED_FAMILIES in scry-core.

The commit hook

The commit runs scry-core's pre-commit check; python -m scry_core.hook --help says what it looks at. Turn it on once per clone:

Shell
$ git config core.hooksPath .githooks

One of its checks is the share of comments and docstrings in each file's bytes. A change that only deletes code raises that share and can fail with no comment touched. Cut a clause in the file it names; never raise the limit.

Tests against a real emulator

A plain pytest starts no emulator. The tests under tests/live/ do:

Shell
$ uv run pytest -o addopts="" -m live tests/live$ uv run python tests/live/run_live_pytest.py

The first runs them one after another. The second runs each test that opens no window as a process of its own, several at once, and then the ones that open a window one at a time.

They run on a DOS program this repository owns, tests/guest/probe.com: a few bytes of assembler that write one log line every three seconds and never exit. Half the cases are about a program that is still running, and the other half read what a program logged.

The cases in protected mode run on a second program the repository owns, tests/guest/dpmi.c. It is a DJGPP program, committed built as dpmi.exe with its nm table dpmi.sym, and runs under CWSDPMI, which its own loader brings in.

On your own program

Point the tests at your conf, and name two words your program logs: one it writes early, and one it writes later. One case waits for something that has not happened yet, and refuses to run if it already has.

Shell
$ DOSBOX_X_LIVE_CONF=/path/to/your.conf \$ DOSBOX_X_LIVE_CWD=/path/to/its/dir \$ DOSBOX_X_LIVE_PROGRAM=YOURAPP.EXE \$ DOSBOX_X_LIVE_MARK=BOOT \$ DOSBOX_X_LIVE_LATE=READY \$     uv run pytest -o addopts="" -m live tests/live

What the demos' cases need

Each demo has a case that runs it, and skips without the program it needs:

Demo Variable What it names
Deluxe Paint (both) DELUXE_PAINT_DIR the directory holding version 1.0's DP.EXE
LineUp LINEUP_MSDOS_DIR a copy of the game's DOS version with its symbol map
Monkey Island MONKEY_ISLAND_CD the directory holding monkey.cue and its BINs
Speed Fight SPEEDF_MSDOS_DIR a copy of the game with EXES/SPEEDF.EXE and EXES/SPEEDF.MAP
ReChip! RECHIP_DIR a built copy of it, with its build/mcp.conf

Two habits keep a demo or a case the same on every computer:

The live test script

tests/live/dosbox_x_live_matrix.py is run as a script. It tries every tool in every state of the machine, at every edge of its arguments and across the calls that share state. Then it runs on real DOS programs a project points it at.

Its docstring has the command and the variables it reads. The ones most used:

Variable What it sets
DOSBOX_X_LIVE_BENCH the folder of real DOS programs the program sections run
DOSBOX_X_LIVE_SECTIONS the sections to run, by letter; AA, names a lone two-letter one
DOSBOX_X_LIVE_JOBS how many sections run at once; unset, half the CPUs; 1, one process
DOSBOX_X_LIVE_DISPLAY the display section R's windows open on; unset, the main one
SCRY_FOCUS_CONTROL 1 lets the focus section open a window in front and move a Space

With DOSBOX_X_LIVE_BENCH unset, or a program missing from it, the case is skipped or BLOCKED and names what is missing. So a fresh clone runs everything the repository's own programs cover.

Each part works on its own copies of the DOS programs, because the debugger writes its files under fixed names into the emulator's working directory (tests/live/live_private.py).

A few cases depend on the computer:

What a window opened behind promises

A start behind does not come to the front, so the keyboard stays where it was. That is all it promises: the window is still there to be seen, and the computer carries the load of every emulator the run starts.

So run the live test script in an account or on a machine nobody is working at, or at an hour agreed with whoever is. Whether a run took the front is the focus section's verdict, read as scry-core's page on these tests says.

What a run checks about the computer

A run refuses a computer that cannot start DOSBox-X, and proves it left none running (scry_core.live_host):

Demos

demos/<name>/demo.py runs one demo end to end. With --update-readme it rewrites the demo's page from a run where every step passed: the two generated blocks of its README, TRANSCRIPT.md, screen.png and loop.webp.

A recording moves the game's clock on. So a demo that compares a sound sample for sample keeps its recordings where its reference sound was made with them, or after the comparison.

The block of the README that adds the server to each client is scry-core's table of clients:

Shell
$ uv run python -m scry_core.install scry_dosbox_x --write

Work from a saved state

A demo or an experiment that spends minutes starting a program is rerun from a state saved at the point of interest. Call state_write(method="save") once; each later run starts the same session and loads it.

Check first that what the run looks at survives a load. A state restores the program's memory and not always the emulator's devices: Monkey Island's screen comes back striped, and its pointer stops following the mouse driver. Memory reads, scans and anything the program computes from its own memory are safe.

Measuring the border and the arrow

The coloured border and the arrow that show a session is on are drawn after the frame goes to capture. So snapshot, screen_view and the emulator's own recordings never show them; they are measured from the computer's own screen.

Before trusting a result, run a control that must fail. Two looks that differ can otherwise come out identical without anything saying so.

Development scripts

tools/bench.py measures what a program costs to run. It takes --conf (the conf to measure) and --cwd (the directory that conf runs in), with no default, and refuses without them. --json, --reps and --song are optional.

The song, the log line it waits for and the make target it calls belong to the program it was written for. A measurement of another program names its own.

tools/mapsweep.py reads real symbol maps where they live, against a manifest that says what each one holds. It fails when the two disagree in either direction. A count that rose against an unchanged file means the map parser has begun to read something that is not a symbol.

Shell
$ uv run python tools/mapsweep.py --manifest <manifest>.json --root /where/those/maps/live

Test fixtures

One file per toolchain is built here and committed under tests/fixtures/:

tests/test_dosbox_x_fixtures.py reads them, so a fresh clone can check that the server reads those formats.

The two Borland routines share their first fifteen characters on purpose: the fixture exercises the name collision the map parser resolves.

Each fixture has its generator, the source it was built from and a build.sh that makes it again. Neither toolchain is in this repository; build.sh takes its location from an environment variable and stops loudly without it.

The description test

A tool's description, its arguments and the server's instructions are all a model has to call the tool from. The description test gives a model only what a client delivers and checks the calls it makes:

Shell
$ uv run python -m scry_core.probe dosbox-x --servers mcp_probe/servers.py \$     --tasks mcp_probe/tasks --check$ uv run python -m scry_core.probe dosbox-x --servers mcp_probe/servers.py \$     --tasks mcp_probe/tasks --runs 3

A task the model keeps getting wrong is tolerated when the server refuses the wrong call and says why: report it with its numbers. A client retries on a refusal, and more description text spends the room the other tools need. Only a wrong call the server accepts with status: ok is a defect.

A file's time on Windows

Windows stamps a file's modification time from a clock that ticks coarser than time.time(). A file created right after a clock read can carry a time a few milliseconds before it. So a plain mtime >= began drops the first file of a run on Windows, and never fails on macOS.