Перейти к содержанию

Отладочные адаптеры

Отладочный адаптер — это процесс, который на самом деле умеет отлаживать конкретный язык. Bugsaur говорит с ним на DAP и в дела языка не вмешивается.

Именно это разделение и делает Bugsaur независимым от языка: добавить язык значит описать адаптер, а не менять отладчик.

Каталог

Адаптеры описываются в TOML-каталоге. Встроенный каталог покрывает четыре адаптера, а профиль ссылается на запись по её id:

[profiles.api]
adapter = "dlv"       # <- id из каталога
program = "cmd/api"
id Язык Команда Транспорт
dlv Go dlv dap --check-go-version=false TCP
codelldb Rust, C, C++ codelldb TCP
debugpy Python python3 -m debugpy.adapter stdio
php PHP php-dbgp-adapter stdio

Откуда берётся каталог

Встроенный каталог всегда служит основой. Поверх него записи читаются из:

  1. $XDG_CONFIG_HOME/bugsaur/adapters.toml
  2. $HOME/.config/bugsaur/adapters.toml

А если задан --adapters <путь> — из этого файла вместо двух предыдущих.

bugsaur gui --adapters ./tools/adapters.toml --project .

Записи сливаются по id: пользовательская запись с существующим id заменяет встроенную, а новый id добавляет адаптер. Отсутствующий файл ошибкой не считается; нечитаемый попадает в предупреждение и пропускается.

Адаптеры ищутся через PATH

command записи разрешается через PATH. Это самая частая причина, по которой сессия не стартует: адаптер установлен, но не там, где его ищет отладчик.

command -v codelldb
export PATH="$HOME/.local/share/nvim/mason/bin:$PATH"

Профиль может указать на конкретный бинарник, вообще не трогая PATH:

[profiles.api]
adapter = "codelldb"
adapter_command = "${root}/vendor/codelldb"
program = "target/debug/api"

Поля записи каталога

Ключ Тип Описание
id строка id, на который ссылаются профили
command строка исполняемый файл, разрешается через PATH
args массив строк его аргументы
cwd строка рабочий каталог процесса адаптера
env таблица строк окружение процесса адаптера
transport "stdio" или таблица tcp как Bugsaur с ним разговаривает
tcp_argument строка аргумент, сообщающий TCP-адаптеру, где слушать; подставляются {host} и {port}
launch_timeout целое секунд на стартовый handshake (launch / attach и configurationDone), когда задержка свойственна адаптеру, а не проекту
launch_arguments таблица умолчания для тела DAP-запроса
build таблица чем собирать программу для этого адаптера — command и args, с {out} и {program}

Два транспорта

stdio — Bugsaur запускает адаптер и общается через его стандартные ввод и вывод. Так работают debugpy и php.

tcp — адаптер слушает порт, а Bugsaur к нему подключается. Так работают dlv и codelldb, и поэтому в их записях есть tcp_argument: Bugsaur выбирает свободный порт и передаёт его.

[adapters.dlv]
id = "dlv"
command = "dlv"
args = ["dap", "--check-go-version=false"]
tcp_argument = "--listen={host}:{port}"
transport = { tcp = { host = "127.0.0.1" } }

Этот раздел