# Build And Packaging Reference

This reference describes host build targets, generated artifacts, ATR contents,
and version behavior. Source of truth: `Makefile`, `tools/package_mutineer_atr.py`,
`tools/package_door_game.py`, and `tools/build_mutineer_basic.py`.

## Editable Inputs

- `source/text/*.bas`: Atari BASIC runtime modules and offline utilities.
- `source/textfiles/ascii/`: editable ASCII caller-facing text.
- `source/textfiles/atascii/`: ATASCII text variants.
- `source/config/MMSAPPS.CFG`: application registry source.
- `source/doorgames/<GAME>/`: separately packaged door sources.
- `mms/src/`: MMS assembler source and public ABI files.
- `VERSION`: authoritative BBS/ATR version string.
- `MMS_VERSION`: authoritative MMS version string; MMS assembly increments its patch field.

Generated directories are disposable: `source/tokenized/`, `source/stage/`,
`source/atr/`, `mms/build/`, `build/`, and `results/`.

## Make Targets

Build targets:

- `make franny`: build `third_party/franny/franny`, the SDX directory-aware ATR packer.
- `make mutineer-basic`: tokenize `source/text/*.bas` into `source/tokenized/`.
- `make mms-com`: assemble base `mms/build/MMS.COM`.
- `make mms-com-hayes`: assemble `MMS-HAYES.COM` with Hayes init enabled.
- `make mms-com-hatabs`: assemble `MMS-HATABS.COM`; this is the default packaged runtime.
- `make mms-com-hatabs-d`: assemble D: wrapping probe build.
- `make mms-com-hatabs-disconnect`: assemble disconnect-watchdog diagnostic build.
- `make mutineer-atr`: build the normal auto-start Mutineer ATR.
- `make mutineer-atr-16mb-manual`: build a large manual-start ATR using `STARUP`.
- `make mutineer-atr-disconnect`: build an ATR with the disconnect-watchdog MMS binary.
- `make door-arena-atr`: build the Arena door ATR under `source/atr/doors/`.

Inspection and validation targets:

- `make mms-abi-check`: verify assembled MMS ABI and HATABS resident size.
- `make mutineer-atr-inspect-current`: inspect the current versioned ATR.
- `make mutineer-atr-inspect`: alias for current ATR inspection.
- `make mutineer-atr-inspect-hatabs`: alias for current HATABS ATR inspection.
- `make docs-audit`: check Markdown links and documented target/tool references.

Runtime/test targets are documented in [Testing And Evidence](TESTING_AND_EVIDENCE.md).

## Version Behavior

`make mutineer-atr`, `make mutineer-atr-16mb-manual`, and
`make mutineer-atr-disconnect` increment the patch field in `VERSION` before
packaging. `tools/package_mutineer_atr.py --no-version-bump` packages using the
current version without changing `VERSION`.

`make version-minor` increments the minor version and resets the patch field.
Every `make mms-com*` target increments the patch field in `MMS_VERSION` and
regenerates `mms/src/version.inc` before assembly. This keeps the MMS banner
version independent from the BBS/ATR `VERSION`.

## Normal ATR Layout

`tools/package_mutineer_atr.py` creates `source/stage/ATARI-MUTINEER/`, then
uses Franny to insert that tree into an SDX ATR.

Root files:

- `AUTOEXEC.BAT`: loads `RHND850.COM`, loads `MMS.COM`, then starts BASIC.
- `AUTOGO`: runs `D1:>CORE>RUNBBS`.
- `RHND850.COM`: Altirra 850 R: handler from `third_party/altirra-additions/`.
- `MMS.COM`: staged from `MUTINEER_MMS_COM` or `mms/build/MMS-HATABS.COM`.
- `README`: on-disk ATR notes.

Directories:

- `CORE`: tokenized runtime modules and offline utilities without `.BAS` extensions.
- `DATA`: config, users, callers, app registry, ACL, file-area metadata, and door catalog.
- `ASCII`: ASCII menus/static text plus `TEXTF`.
- `ATASCII`: ATASCII menus/static text plus `TEXTF`.
- `MAIL`: default message base files.

## Manual-Start ATR

`make mutineer-atr-16mb-manual` writes `AUTOEXEC.BAT` that loads `RHND850.COM`
and `MMS.COM`, prints a start hint, and does not run the BBS automatically. The
default startup file is `STARUP`, and the on-Atari command is:

```text
BASIC /I <<D1:STARUP
```

`tools/package_mutineer_atr.py --manual-start --startup-name NAME` requires a
1-8 character alphanumeric startup name.

## Door ATR Packaging

`make door-arena-atr` runs `tools/package_door_game.py ARENA`. Door package
sources live under `source/doorgames/<GAME>/`, and output ATRs are written under
`source/atr/doors/`.

Door packages include the game BASIC file, optional overlays/data/text, and an
install note. The main BBS only needs a matching `D1:>DATA>DOORS.CFG` row and a
mounted disk/path matching that row.

## Clean

`make clean` removes generated `build`, `results`, `atrs`, `screens`,
`source/tokenized`, `source/stage`, `source/atr`, and Python `__pycache__`
directories, then recreates the main generated source output directories.