Sprinter: добавить отладку C-исходников и интеграцию VS Code

2026-09-15 17:58:41 +03:00
parent 50c6e56b7b
commit e4695b8281
62 changed files with 7147 additions and 27 deletions
@@ -0,0 +1,81 @@
+# Sprinter MAME Debug
+
+VS Code-клиент сборки и отладки для `toolchain/sdbg_dap.py`. Режим `launch` сам
+поднимает изолированные MAME и session server; перед `attach` их запускают
+вручную.
+
+> [!WARNING]
+> Native Windows пока не поддерживает полный launch/attach: `windows`
+> выбирает только debugger provider MAME, а host-часть всё ещё зависит от
+> `fcntl`, Unix domain sockets и Unix launcher.
+
+Для разработки расширение можно открыть отдельным окном VS Code и запустить
+Extension Development Host. Конфигурация проекта:
+
+```sh
+code --extensionDevelopmentPath="$PWD/toolchain/vscode-sprinter-debug" "$PWD"
+```
+
+Python выбирается без зависимости от `PATH` GUI: при наличии local
+`.python-version` используется `~/.pyenv/shims/python`; для внешнего workspace
+без неё расширение ищет установленный `~/.pyenv/versions/3.12*/bin/python`.
+Версия local передаётся задаче через `PYENV_VERSION`, поэтому сборка работает
+и если `project` лежит вне workspace. При необходимости задайте абсолютный путь через
+`sprinterDebugger.pythonCommand`. Выбранные пути печатаются в канале Output
+`Sprinter MAME Debug`.
+
+```json
+{
+  "type": "sprinter-mame",
+  "request": "launch",
+  "name": "Sprinter MAME: Launch",
+  "build": "${workspaceFolder}/tests/hello/.sprinter-cc-hello"
+}
+```
+
+Перед F5 расширение по умолчанию находит Makefile проекта по пути `build` и
+выполняет задачу `make SRC_DEBUG=1` в каталоге проекта через local Python 3.12.
+Ошибки SDCC с файлом и строкой попадают в Problems. При ненулевом коде
+сборки debug launch отменяется до старта MAME. Для нестандартной раскладки
+укажите `"project": "${workspaceFolder}/path/to/app"`; для уже собранного
+пакета можно задать `"autoBuild": false`. Явный `preLaunchTask` остаётся под
+контролем стандартного механизма VS Code и отключает автоматическую задачу
+расширения.
+
+Команда палитры `Sprinter: Build Active Project` строит проект открытого
+C-файла. В `Tasks: Run Task` доступны задачи `Sprinter: Build ...` для
+Makefile, включающих `app.mk`. Сборка не заменяет исходный `make` и не пишет
+в общий образ дискеты MAME.
+
+По умолчанию patched backend `sdbg` не открывает отдельное окно debugger MAME.
+Чтобы пользоваться им одновременно с VS Code, добавьте в launch:
+
+```json
+"debugger": "osx"
+```
+
+Без project patch можно задать `auto`; явные native provider: `osx` на macOS,
+`windows` в Windows, `qt` или `imgui` в Linux. Host-инструменты sdbg сейчас
+рассчитаны на macOS/Linux (`fcntl`, Unix sockets и Unix launcher); native
+Windows transport и end-to-end тесты ещё требуются.
+
+Готовность DSS определяется по стабильному prompt в VRAM. `dssTimeout`
+задаёт таймаут (по умолчанию 30 секунд), а `launchAt` — необязательное самое
+раннее время ввода команды.
+
+Ручной attach:
+
+```json
+{
+  "type": "sprinter-mame",
+  "request": "attach",
+  "name": "Sprinter MAME: Attach",
+  "socket": "/tmp/sprinter-sdbg.sock"
+}
+```
+
+Сейчас доступны точки по исходнику/функции, `logMessage` с безопасными
+подстановками `{variable}`, один проверенный frame, регистры, поддержанные
+global/static, continue/pause и instruction step. Source step поддержан для
+F10/F11/Shift+F11; банковский step-over и step-out проходят
+служебные trampoline до следующей C-позиции.