# 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](BUILD_AND_PACKAGING.md),
[Altirra 850 Modem](ALTIRRA_850_MODEM.md),
[Tools Reference](TOOLS_REFERENCE.md), and
[Testing And Evidence](TESTING_AND_EVIDENCE.md).

## 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:

```sh
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:

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

## Building

Common targets:

```sh
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:

```sh
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:

```sh
telnet 127.0.0.1 6507
```

## Automated Tests

Build and static checks:

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

Runtime tests:

```sh
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:

```sh
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:

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

Then confirm the port is clear:

```sh
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](TROUBLESHOOTING.md) for current operational
failure symptoms and [Runtime Architecture](RUNTIME_ARCHITECTURE.md)
for module-switching and MMS handoff behavior.