docs: описать разделение тулкита, MAME и приложений

2026-09-15 17:59:13 +03:00
parent e4695b8281
commit 5323b168a7
1 changed files with 251 additions and 0 deletions
@@ -0,0 +1,251 @@
 # Разделение 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 и публикация релизов выполняются отдельной задачей после
 согласования этого плана.