Linux Developers Guide

This guide describes a Linux host setup for developing Atari Mutineer and MMS, building ATR images, launching Altirra under Wine, and testing through the host telnet path.

For command-level references, see Build And Packaging, Altirra 850 Modem, Tools Reference, and Testing And Evidence.

Workspace

The repository is organized around these paths:

• source/text/: editable Atari BASIC modules and offline tools.
• source/textfiles/ascii/: editable ASCII text displayed by the BBS.
• source/textfiles/atascii/: ATASCII variants of caller-facing text.
• source/tokenized/: generated tokenized .BAS and .LST files.
• source/stage/: generated ATR staging area.
• source/atr/: versioned ATR outputs.
• source/config/: build-time registry data such as MMSAPPS.CFG.
• mms/src/: resident MMS assembler source.
• mms/build/: assembled MMS binaries and listings.
• tools/: host build, packaging, launch, inspection, and test scripts.
• tests/: focused Atari-side probe programs.
• docs/: developer and sysop documentation.

Generated files are disposable. Edit BASIC in source/text/, text assets in source/textfiles/, MMS assembler in mms/src/, and build configuration in source/config/.

Host Requirements

Install the normal build and test dependencies:

sudo apt install make python3 python3-pexpect wine xvfb telnet

The workspace also expects these Atari-oriented tools and assets:

• mads in PATH, for assembling MMS.
• local third_party/franny/franny, built by make franny, for SDX directory-aware ATR images.
• Altirra under tools/altirra/4.40/.
• A Wine prefix at .wine-altirra/ with drive_z mapped to the workspace.
• SpartaDOS X cartridge image at third_party/SDX450_maxflash8.car.
• RHND850.COM staged at third_party/altirra-additions/RHND850.COM.

Check the critical tools before building:

command -v mads
make franny
command -v wine
command -v xvfb-run
command -v telnet

Building

Common targets:

make mutineer-basic
make mms-com-hatabs
make mutineer-atr
make mutineer-atr-16mb-manual
make door-arena-atr
make mutineer-atr-inspect-current

make mutineer-atr increments the patch number in VERSION, tokenizes BASIC, assembles MMS with HATABS enabled, and writes a versioned ATR under source/atr/.

make mutineer-atr-16mb-manual builds a large manual-start ATR. It loads RHND850.COM and MMS.COM, writes STARUP, and does not auto-run the BBS.

make door-arena-atr builds a separate door package from source/doorgames/ARENA/ under source/atr/doors/.

Running Altirra

Launch the current ATR with:

make altirra-850-run

The launcher writes an Altirra profile under results/altirra-850/, copies it to tools/altirra/4.40/Altirra.ini, mounts the current ATR, mounts the SDX cartridge, and configures the emulated 850 modem listener. The default caller port is 6507.

Useful environment variables:

• MUTINEER_ATR=/path/to/file.atr: override the ATR.
• MUTINEER_MODEM_PORT=6507: override the modem listener port.
• MUTINEER_TELNET=1: enable Altirra telnet negotiation.
• MUTINEER_ALTIRRA_DEBUG_LOG=/path/to/log.txt: capture Altirra debug output.
• MUTINEER_EXTRA_DISK=/path/to/door.atr: mount an additional disk.

Manual caller connection:

telnet 127.0.0.1 6507

Automated Tests

Build and static checks:

make mutineer-basic
make mms-com-hatabs
make mms-abi-check
make mutineer-atr-inspect-current

Runtime tests:

make mms-hatabs-probe-api
make mms-hatabs-probe-mixed
make mms-hatabs-probe-input
make mutineer-telnet-test
make mutineer-xmodem-test
make mutineer-regression-test
make acceptance
make acceptance-hatabs

Important result paths:

• build/logs/: command logs from Makefile targets.
• build/mms-abi.json: MMS ABI verification.
• build/mutineer-atr-manifest.json: ATR inspection evidence.
• results/mutineer-telnet/<timestamp>/: telnet transcript, coverage, and JSON result.
• results/mutineer-xmodem/<timestamp>/: transfer transcript and result.
• results/mutineer-evidence.json: combined acceptance evidence.

Docs checks:

make docs-audit

This verifies required Markdown pages, local links, documented Make targets, and documented tool references.

Cleaning Stale Processes

If a test hangs or the modem port stays busy, stop Wine and Altirra before trying again:

pkill -f Altirra || true
pkill -f wineserver || true
wineserver -k || true

Then confirm the port is clear:

ss -ltnp | grep 6507 || true

Troubleshooting

• missing tool: mads: install the tool or add it to PATH.
• missing Franny binary: run make franny.
• Altirra launches but no caller port appears: check .wine-altirra/drive_z, tools/altirra/4.40/Altirra.ini, and results/altirra-850/*.ini.
• Telnet connects but no HIT <RETURN> appears: check that RHND850.COM, MMS.COM, and the SDX cartridge were loaded, then inspect the latest Altirra debug log if enabled.
• Password entry shows *: this is expected; normal input should echo through MMS/HATABS.
• XMODEM hangs: make sure the test uses binary telnet negotiation and that XFER receives a path no longer than the current handoff field supports.
• ATR inspection fails: inspect build/mutineer-atr-manifest.json and rebuild from a clean tokenized/stage output.
• Docs audit fails: fix the referenced link, Make target, or tools/*.py filename; the audit is intentionally strict about local references.

Development Notes

Packaged runtime modules live under D1:>CORE> without .BAS extensions. Core data lives under D1:>DATA>, text assets under D1:>ASCII> and D1:>ATASCII>, and default message bases under D1:>MAIL>.

MMS HATABS is the default packaged communication layer. The D: and P: HATABS wrappers are guarded build options and should not be described as production behavior unless their probes and acceptance tests pass.

Use Troubleshooting for current operational failure symptoms and Runtime Architecture for module-switching and MMS handoff behavior.