Tools Reference

This page documents host-side scripts under tools/. Use make targets when available; call scripts directly for diagnostics or non-default arguments.

Build And Packaging Tools

tools/build_mutineer_basic.py

• Purpose: tokenize standalone Atari BASIC modules from source/text/ into source/tokenized/.
• Arguments: --source-dir, --build-dir.
• Used by: make mutineer-basic.

tools/tokenize_atari_basic.py

• Purpose: tokenize one Atari BASIC source.
• Arguments: optional source path, -o/--output.
• Used by: tools/build_mutineer_basic.py.

tools/write_mms_version_inc.py

• Purpose: increment MMS_VERSION patch and generate mms/src/version.inc.
• Used by MMS assembly targets.

tools/build_mms_apps.py

• Purpose: compile source/config/MMSAPPS.CFG into fixed-record MMSAPPS.DAT.
• Arguments: --config, --output, --generation.
• Output default: source/stage/ATARI-MUTINEER/MMSAPPS.DAT.

tools/package_mutineer_atr.py

• Purpose: stage the full BBS tree and create a versioned SDX ATR.
• Arguments: --out, --no-version-bump, --size, --manual-start, --startup-name.
• Env: MUTINEER_MMS_COM overrides the staged MMS binary.
• Outputs: source/stage/ATARI-MUTINEER/ and source/atr/atari-mutineer-v*.atr.

tools/package_door_game.py

• Purpose: package a separate door game ATR from source/doorgames/<GAME>/.
• Arguments: optional game name, --size.
• Output: source/atr/doors/atari-mutineer-door-<game>-v*.atr.

tools/extract_dos2_atr.py

• Purpose: extract simple DOS 2.x single-density ATR contents.
• Arguments: ATR path and optional output directory.
• This is a utility for inspection, not the normal SDX packaging path.

tools/versioning.py

• Purpose: shared helpers for reading and incrementing VERSION.
• Used by package/build targets.

Altirra And Emulator Tools

tools/run_altirra_850.py

• Purpose: launch Altirra under Wine with generated 850/modem profile.
• Env: MUTINEER_ATR, MUTINEER_MODEM_PORT, MUTINEER_CONNECT_RATE, MUTINEER_TELNET, MUTINEER_TELNETLF, MUTINEER_USE_SDX, MUTINEER_CART, MUTINEER_CART_MAPPER, MUTINEER_EXTRA_DISK, MUTINEER_ALTIRRA_DEBUG_LOG.
• Outputs: profile under results/altirra-850/, copied to tools/altirra/4.40/Altirra.ini.

tools/run_atari800_rdevice_probe.py

• Purpose: probe atari800 native network R: behavior.
• Env: SDX_CART, BASIC_PARSER.
• This is not the default Mutineer acceptance path.

Probe And Acceptance Tools

tools/package_mms_hatabs_probe_atr.py

• Purpose: build tiny SDX ATRs for focused MMS HATABS probes.
• Argument: --mode with api, mixed, input, sysop, donly, dmodem, dstep, or full.
• Env: MMS_PROBE_DIAL_HOST, MMS_PROBE_DIAL_PORT, MMS_PROBE_BASIC_COMMAND, MMS_PROBE_ECHO_BOOT, MUTINEER_MODEM_PORT, MUTINEER_MMS_COM.
• Outputs: source/atr/mms-hatabs-probe-<mode>.atr.

tools/run_mms_hatabs_probe.py

• Purpose: run a probe ATR under Altirra and capture host telnet output.
• Argument: --mode with the same choices as the package tool.
• Env: MMS_HATABS_PROBE_MODE, MUTINEER_MODEM_PORT, MMS_HATABS_PROBE_TIMEOUT, MMS_HATABS_PROBE_CONNECT_DELAY, MMS_HATABS_PROBE_CONNECT_MODE, MUTINEER_MMS_COM, MUTINEER_ALTIRRA_DEBUG.
• Outputs: results/mms-hatabs-probe/<mode>/<timestamp>/.

tools/run_mutineer_telnet_test.py

• Purpose: run scripted telnet coverage through Altirra's modem listener.
• Env: MUTINEER_MODEM_PORT, MUTINEER_TEST_TIMEOUT, MUTINEER_CONNECT_DELAY, MUTINEER_SEND_DELAY, MUTINEER_TEST_SCENARIO, MUTINEER_LINE_ENDING, MUTINEER_CLIENT, MUTINEER_ATR, MUTINEER_USE_SDX, MUTINEER_CART, MUTINEER_CART_MAPPER, MUTINEER_EXTRA_DISK, MUTINEER_TELNETLF, MUTINEER_ALTIRRA_DEBUG, MUTINEER_MMS_COM.
• Outputs: results/mutineer-telnet/<timestamp>/.

tools/run_mutineer_xmodem_test.py

• Purpose: run scripted XMODEM upload/download coverage through Altirra.
• Env: MUTINEER_MODEM_PORT, MUTINEER_XMODEM_TIMEOUT, MUTINEER_CONNECT_DELAY, MUTINEER_ATR, MUTINEER_ALTIRRA_DEBUG.
• Outputs: results/mutineer-xmodem/<timestamp>/.

tools/run_mutineer_regression_test.py

• Purpose: verify normalized transcript markers from a telnet test run.
• Arguments: --run-dir, --out, --markers.
• Output default: build/mutineer-regression.json.

tools/mutineer_evidence.py

• Purpose: collect acceptance outputs into one evidence manifest.
• Argument: --out.
• Output default: results/mutineer-evidence.json.

Inspection And Audit Tools

tools/inspect_mutineer_atr.py

• Purpose: inspect packaged ATR contents and emit acceptance evidence.
• Arguments: --atr, --out.
• Output default: build/mutineer-atr-manifest.json.

tools/mms_abi_check.py

• Purpose: compare assembled MMS listings against expected public ABI and HATABS resident-size limits.
• Arguments: --listing, --hatabs-listing, --basic, --out.
• Output default: build/mms-abi.json.

tools/docs_audit.py

• Purpose: check required docs pages, local Markdown links, documented Make target names, and documented tools/*.py references.
• Used by: make docs-audit.