# 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-позиции.