# Разделение Sprinter-CC, MAME и приложений

Статус: план, без переноса файлов. Дата: 2026-09-15.

## Цель и границы

Тулкит, эмулятор, примеры и реальные приложения должны разрабатываться и
версионироваться независимо. Приложение собирается из собственного клона,
если ему указан только путь к установленному Sprinter-CC. Для запуска в
эмуляторе дополнительно указывается путь к подготовленной среде MAME либо
необходимые отдельные пути. Ни соседний репозиторий Examples, ни исходники
MAME приложению не нужны.

Предлагаемая раскладка на машине разработчика:

```text
~/Projects/DIY/Z80/Sprinter/
├── C-Compiler/                  # Sprinter-CC
├── MAME/                        # fork MAME, сборки и локальная среда запуска
├── Examples/                    # один Git-репозиторий примеров
├── Applications/                # каталог без собственного Git
│   ├── SprPoP/                  # самостоятельный Git-репозиторий
│   ├── Volkov/                  # самостоятельный Git-репозиторий
│   └── PoP-Archive/             # архивный проект, если история нужна отдельно
└── VSCode-Sprinter/             # Git-репозиторий расширения VS Code
```

Имена `C-Compiler`, `Volkov` и `PoP-Archive` здесь рабочие; адреса Git remote
новых репозиториев и окончательные имена фиксируются до миграции. Папка
`Applications/` не становится общим репозиторием: каждый продукт имеет свою
историю, релизы, игнорируемые ресурсы и тесты. Физическое расположение рядом
удобно, но не входит в контракт сборки.

## Что принадлежит каждому проекту

| Проект | Что остаётся/переходит | Причина |
|---|---|---|
| Sprinter-CC | `bin/`, `runtime/`, `libc/`, `libbgi/`, `lib/`, общие `toolchain/`, `tests/`, `testkit/`, `app.mk`, справочник API, платформенные исследования, `release_docs/`, рецепт SDCC в `third_party/` | Это target SDK, его ABI, инструменты и собственные регрессионные тесты. libc/libbgi пока остаются вместе: их версия и ABI тесно связаны с `sprinter-cc`; дальнейшее выделение возможно после стабильного интерфейса. |
| MAME | Нынешний `mame/sources/MAME` со своим Git, изменения драйвера/OSD, патч debugger backend, общие `mamebridge` и `mame_mcp.py`, рецепты stock/sdbg сборок | Изменения ядра и общий транспорт MCP должны проверяться и выпускаться вместе с конкретной ревизией MAME. |
| Examples | Нынешние `examples/balls`, `mdview`, `mdview2`, `rpgwalk`, `scroll`, `space` и относящиеся к ним ресурсы/документы | Это демонстрации SDK с общей версией. Один репозиторий избегает множества мелких релизов. |
| SprPoP | Всё `applications/SprPoP/`: исходники, конверторы, тесты, собственные ресурсы и планы | Уже почти автономное приложение; оригинальные ресурсы и дальше остаются внешними. |
| Volkov | Всё `applications/Volkov/`: исходники, сценарии MAME, собственные тестовые носители и документы | Продукт и его проверки должны развиваться без дерева тулкита. |
| PoP-Archive | `applications/PoP/` как архив прежних PoC/roomtest и исследований | Не смешивать прежнюю историю с активным SprPoP. Если архив не нужен как рабочий клон, сохранить Git-историю и документы в отдельном архивном репозитории. |
| VSCode-Sprinter | Нынешний `toolchain/vscode-sprinter-debug`: extension, задачи сборки, конфигурации и тесты клиентской части | У расширения свои версии, упаковка VSIX и цикл обновления. Отладочный Python backend остаётся в SDK. |

`applications/DN/DosNavigator` и вложенные чужие клоны в PoP/Volkov —
референсы, не Sprinter-приложения. Их не превращать в продуктовые репозитории
и не коммитить вместе с портами. Локально их можно хранить в `References/`
или получать по воспроизводимой инструкции с указанием upstream и revision.
`docs/sources/`, `docs/extra/` и скачанный SDCC также не являются новым
проектом: это игнорируемые справочные/загруженные материалы. Отдельно
проверить, какие tracked файлы `third_party/16x16-RPG-characters` нужны
`rpgwalk` и старому PoP; каждый потребитель получает собственный ресурс или
явный рецепт его загрузки. Лицензии и происхождение сохранить.

## Контракт сборки и запуска приложения

`SPRINTER_ROOT` указывает на готовый Sprinter-CC. Это единственный внешний
путь, обязательный для сборки `.exe`, host-тестов и собственных генераторов
ресурсов. В `app.mk` убрать вывод MAME из `PROJ_ROOT`; оставить
совместимый alias `PROJ_ROOT := $(SPRINTER_ROOT)` там, где это необходимо на
переходный период. Приложения проверяют, что по пути существуют
`bin/sprinter-cc`, `app.mk` и нужные библиотеки, и сообщают ошибку до начала
сборки. При отсутствии `SPRINTER_ROOT` не угадывать прежнее `../..`: после
переноса такой путь может случайно указывать на чужой каталог.

`MAME_HOME` — необязательный для сборки путь к подготовленной **среде запуска**
MAME, а не к его исходникам. Стандартные пути соответствуют нынешнему
`mame/v306` и допускают переопределение из окружения, аргументов `make` или
локального игнорируемого файла настроек. Если `MAME_HOME` не задан,
необходимые пути можно указать отдельно; отсутствие обоих источников
диагностировать в цели запуска, не превращая пустое значение в `/mame.arm`:

```make
MAME_BIN              ?= $(MAME_HOME)/mame.arm
MAME_ROMPATH          ?= $(MAME_HOME)/roms
MAME_DSS_IMAGE        ?= $(MAME_HOME)/IMG/dss171u.img
MAME_SYSTEM_HDD_IMAGE ?= $(MAME_HOME)/IMG/sp_hdd_sys.chd
MAME_BIOS             ?= v3.06
```

`MAME_BIOS` — имя варианта для аргумента `-bios`; ROM-файлы MAME ищет в
`MAME_ROMPATH`. `MAME_SYSTEM_HDD_IMAGE` добавлен потому, что системный CHD
нужен существующим сценариям. Если используется CD, NeoGS или второй
системный носитель, пути к ним сделать отдельными необязательными настройками
профиля запуска; не прибивать их к Makefile каждого приложения. Уточнить по
фактическим сценариям, когда нужен `MAME_DSS_IMAGE`: обычный `run`, тест и
DAP-launch должны брать один источник настройки, даже если конкретный профиль
не монтирует DSS-дискету.

`MAME_HOME/mame.arm` — стандартный установленный бинарник, а stock/sdbg
сборки находятся отдельно и выбираются явным `MAME_BIN`. Сборка одного
варианта не перезаписывает другой и не меняет молча активный бинарник.
Для запуска с нетипичной установкой можно переопределить каждый путь, не
копируя ROM/CHD в каталог приложения. Все цели запуска валидируют свои
фактически используемые файлы и выводят проверенный путь в диагностике.

Собственный `.img`/`.chd`, результаты сценариев, снимки, Lua-скрипты и
журнал приложения лежат в его `build/` (или другом локальном выходном
каталоге). MAME получает готовый образ аргументом `-flop1`/`-hard2`. Общие
`IMG/mc.img` и `IMG/test_hdd.chd` больше не являются выходами сборки
приложения. `make hdd` готовит локальный образ; `make run` запускает его
без `mame-link`. Для нескольких сценариев создавать отдельные носители и
state-каталоги, чтобы параллельный запуск не перезаписывал чужой тест.
Конфигурация разработчика не содержит абсолютных личных путей в Git.
Для `.img` нужен упаковщик из SDK; для `.chd` нынешний `make_hdd.sh`
дополнительно использует внешние `mtools` и `chdman`. Зафиксировать эти
host-зависимости и проверять их перед упаковкой. `chdman` можно находить
через `PATH` либо переопределяемый `CHDMAN_BIN`; путь к исходникам MAME или
полная установка эмулятора для самой сборки `.exe` не нужны.

Временное состояние MAME (`cfg`, `nvram`, `diff`, `snapshot`, IPC) создаётся
в отдельном каталоге сессии. Обычный запуск, автотест и DAP используют одну
функцию/профиль разрешения путей, но разные режимы жизненного цикла и
разные локальные диски. Не требовать закрывать все чужие процессы MAME по
общему шаблону: предотвращать конфликт только за конкретный изменяемый
носитель/IPC-сеанс. Закрытие MAME не должно терять лог и снимки теста.

## Граница MAME и отладки

В репозитории MAME держать точную базовую ревизию fork, stock сборку и
патченный `sdbg` backend как явную ветку/патч с рецептом сборки. Локальный
checkout уже имеет отдельный `.git` и remote
`https://git.snark13.com/snark13/MAME.git`; переносить его как источник,
не копировать `.git` внутрь нового репозитория тулкита. ROM, DSS, CHD,
скачанные assets, исполняемые файлы и пользовательский state игнорировать.
Инструкция установки создаёт стандартный `MAME_HOME`; она проверяет
наличие/версию файлов, но не распространяет их через Git без отдельной
проверки лицензий и источника.

В Sprinter-CC остаются `--src-debug`, C/asm-карта, debug package,
`toolchain/sdbg*`, Python DAP, launcher и Sprinter-специфичный плагин
`sdbgbridge`. Приложение знает только debug build и свои файлы. Launcher
принимает `MAME_HOME` и все переопределяемые пути из общего профиля;
`-pluginspath`, IPC, ожидание DSS, установка точек и `sdbg` протокол — его
внутренняя работа. Сочетание с родным окном MAME остаётся опцией:
`osx` на macOS, `qt`/`imgui` на Linux по возможностям сборки. Stock MAME
можно выбрать для поддержанного штатного backend; режим `sdbg` требует
соответствующей патченной сборки и должен проверять её до запуска.
Native Windows launch/attach пока не обещать: текущий host transport зависит
от Unix sockets/`fcntl` и не прошёл полный Windows сценарий.

Общий `mamebridge` и `mame_mcp.py` остаются с fork MAME, пока используются
как общие инструменты MAME. Sprinter-специфичному `sdbgbridge` отдельный Git
репозиторий сейчас не нужен: он версионируется с DAP-протоколом в SDK и
загружается через `-pluginspath`. Текущий `toolchain/run-mame-mcp.sh` и
`.codex/config.toml` убрать от предположения `mame/sources/MAME` внутри
тулкита; для общего MCP использовать путь к установленному MCP-серверу
MAME, а для Sprinter C-уровня — DAP/session server SDK. Зафиксировать версию
протокола bridge и совместимость SDK ↔ MAME; несовпадение показывать как
ошибку, а не как зависание отладки.

Репозиторий VSCode-Sprinter содержит только extension и клиентские тесты.
По умолчанию он обнаруживает DAP-инструмент из `SPRINTER_ROOT` либо получает
явную настройку пути; не ищет `toolchain/sdbg_dap.py` в открытом workspace.
Build task выполняет `make SRC_DEBUG=1 SPRINTER_ROOT=...` в каталоге
приложения, F5 передаёт debug package, MAME-профиль и собственные data файлы
адаптеру SDK. Поиск проектов не должен зависеть только от буквального
`include $(PROJ_ROOT)/app.mk`: определить простой стабильный признак проекта
или явный каталог в `launch.json`. Версии VSIX, SDK и поддержанной ревизии
MAME документируются вместе; extension не копирует Python backend.

## Известные связи, которые нужно заменить

| Сейчас | Замена и причина |
|---|---|
| Корневые `Makefile` и `app.mk` собирают examples/MAME и пишут общую floppy/HDD под `mame/v306` | В SDK оставить `make`/`size-check`/собственные тесты; упаковщик принимает выходной путь и MAME-профиль. Примеры собираются в Examples, MAME — в MAME. Удаление корневых целей без замены лишило бы пользователя привычного run: документировать новые команды и при необходимости оставить переходные targets с явной подсказкой. |
| `make host-tests` SDK запускает `applications/SprPoP/tests/host` | Тесты игры вызываются из SprPoP по `SPRINTER_ROOT`; SDK тестирует только SDK. При этом общий `testkit` остаётся SDK. |
| SprPoP `mame-link` меняет `MAME_HOME/IMG/test_hdd.chd` | `make run` передаёт `build/hdd/sprpop.chd` как `-hard2`; состояние установки MAME не меняется. |
| Volkov `hdd-p5-viewer` собирает `examples/mdview2` | Перенести внутрь Volkov небольшой viewer fixture либо зафиксированный тестовый EXE/исходник с лицензией. Предпочтение — локальный fixture, потому что тест проверяет запуск дочерней программы, а не функциональность mdview2. Проверить, какие свойства реального viewer обязательны, перед заменой. |
| Volkov `tests/run_mame_hdd.sh` и другие сценарии считают MAME `../../mame/v306` | Принять общие переменные MAME и локальный образ, не менять сценарные Lua-файлы без необходимости. |
| PoP `roomtest`, `bgtest`, `poc` ищут собственные `toolchain/` и `SDLPoP` через корень SDK | Ввести `POP_ROOT`/`APP_ROOT` внутри PoP и локальные пути к референсам; общие SDK-инструменты оставить по `SPRINTER_ROOT`. Не переносить чужие источники и оригинальные игровые данные в Git. |
| Examples Makefiles и `rpgwalk/conv_sprites.py` рассчитаны на `../..` и тулкитский `third_party/` | Подключать SDK по `SPRINTER_ROOT`, resource fixture держать рядом с примером либо получать по зафиксированному рецепту. |
| `toolchain/mame_interactive.py`, `tests/sdbg/run_mame_probe.py`, `sdbg_launcher.py` выводят MAME из `PROJECT_ROOT` | Ввести общий профиль путей, локальные образы и явные аргументы; offline `sdbg-tests` не должен требовать MAME. |
| `toolchain/make_release.sh` включает `examples/` в архив SDK, а README описывает общий диск | Выпускать Examples отдельно либо собирать составной release по зафиксированной версии Examples; сначала определить контракт релиза, затем изменить архив и обе документации. |
| Исследовательские docs и код библиотек ссылаются на `applications/PoP/...` и `mame/sources/...` | Сохранять контекст исследования, но заменять рабочие инструкции и относительные ссылки ссылками на соответствующий репозиторий/revision. Архивные наблюдения не удалять. |

## История Git, внешние ресурсы и совместимость

До выделения репозиториев инвентаризировать незакоммиченные/неотслеживаемые
файлы в корне и отдельный dirty checkout MAME. Среди новых файлов сейчас
находятся DAP, extension, MCP-плагин, MAME patch и документы: простое
`git subtree split` по старому HEAD их потеряет. Сначала сохранить работу
в подходящих коммитах/ветках или проверенных патчах; не сбрасывать и не
перезаписывать пользовательские изменения. Затем выделить историю
`examples/`, `applications/SprPoP/`, `applications/Volkov/` и PoP через
`git subtree split` либо `git filter-repo`, проверяя состав каждого нового
Git дерева. Для MAME использовать его существующую историю, а не историю
родительского SDK, где `mame/` игнорируется.

Новый `.gitignore` каждого проекта покрывает собственные `.exe`, объекты,
debug packages, носители, снимки, внешние источники и секреты локального
конфига. Не переносить автоматически вложенные сторонние `.git` как gitlinks
или submodules. Для ресурсов, которые не входят в Git, указать источник,
контрольную сумму/revision и способ восстановления; релиз и CI не должны
молча зависеть от файлов конкретной машины. Если приложению нужен SDK с
определённым ABI, фиксировать поддерживаемый релиз/commit SDK в его README
или manifest, не пытаться угадывать его по соседнему каталогу.

Во время перехода обеспечить минимальный период совместимости старой
структуры: сначала добавить переменные и альтернативные пути, проверить
старые вызовы, затем переносить деревья. После миграции убрать fallback на
старые относительные пути и диагностировать устаревшие команды. Это не
должно оставлять два параллельных способа записи в общий носитель.

## Порядок работ и критерии готовности

1. **Зафиксировать текущую базу.** Список tracked/untracked файлов,
   отдельный Git MAME, лицензии/внешние ресурсы, базовые результаты сборок
   и smoke-тестов. Сохранить незавершённую отладочную и прикладную работу.
   Критерий: никакой исходник не теряется при выделении истории.
2. **Стабилизировать контракт SDK.** В `app.mk` разделить build и run,
   реализовать `SPRINTER_ROOT`, `MAME_HOME` и переопределения, упаковку
   локального образа с проверкой `mtools`/`chdman`, общий профиль путей
   и диагностику отсутствующих файлов. Перевести автотесты/launcher без
   переноса дерева.
   Критерий: приложение собирается без MAME и запускается с нестандартным
   `MAME_BIN`/ROM/DSS/System HDD.
3. **Подготовить MAME отдельно.** Сохранить fork с точной baseline-revision,
   stock/sdbg сборки и проверенным способом подготовки `MAME_HOME`.
   Перенести MAME patch/общий MCP к их владельцу, проверить обоих провайдеров.
   Критерий: два бинарника существуют одновременно, ROM/CHD и state не
   коммитятся, patched DAP launch проверен.
4. **Выделить Examples.** Переписать относительные пути и источник RPG
   графики, определить формат релиза SDK+Examples. Критерий: каждый пример
   собирается из собственного клона Examples при одном `SPRINTER_ROOT`,
   локальные диски не затрагивают MAME или соседние проекты.
5. **Выделить приложения по одному.** Сначала SprPoP как наиболее близкий
   к автономному контракту, затем Volkov с локальным viewer fixture, затем
   архив PoP с его референсами. Переписать тесты и run-скрипты, сохраняя
   их документы и историю. Критерий: каждый продукт собирается и проходит
   доступные host/MAME проверки из изолированного клона без Examples и
   других приложений.
6. **Выделить extension.** Научить VS Code находить SDK DAP независимо от
   workspace, запускать build/run/debug приложения и показывать ошибки
   разрешения путей/версий. Проверить VSIX в отдельном workspace SprPoP
   или Volkov, а не только в `C-Compiler`. Критерий: F5 строит debug package,
   ждёт DSS, доходит до `main`, принимает breakpoint/logpoint и клавиатуру;
   опция родного окна MAME работает на macOS. Windows остаётся явно
   ограниченной до отдельной реализации host transport.
7. **Очистить SDK и документы.** Заменить корневые цели, release-скрипт,
   README, `AGENTS.md`, инструкции автотеста/отладки и рабочие ссылки.
   Проверить `make`, `make -C libc`, `make -C libbgi`, `make size-check`,
   SDK host/sdbg tests и отдельные проекты. Критерий: в SDK нет tracked
   приложений/примеров и игнорируемого вложенного MAME; инструкции используют
   новые пути, а архивные исследования остаются доступны.

Каждый этап заканчивается проверкой в отдельном клоне и просмотром Git diff,
а не одним успешным запуском в старом общем дереве. Реальные переносы,
новые Git remote и публикация релизов выполняются отдельной задачей после
согласования этого плана.