Первая сессия отладки

Эта страница проводит путь от проекта, который вы ни разу не отлаживали в Bugsaur, до отладчика, остановленного на точке останова и показывающего переменную. Займёт несколько минут.

Каждый шаг говорит, что должно произойти. Если не произошло — шаг говорит, куда смотреть.

Перед началом

Нужен bugsaur в PATH и адаптер для вашего языка. Если этого ещё нет, сначала пройдите Установку и возвращайтесь.

Разбор идёт на примере Rust. Для остальных языков форма та же — меняются только адаптер и значение program.

Шаг 1 — Описать проект

В корне проекта:

bugsaur init

Что должно произойти: появляется файл .bugsaur/config.toml, команда печатает, куда его записала.

version = 1
default = "app"

[profiles.app]
adapter = "codelldb"
program = "target/debug/app"

Ничего не сгенерировалось

init опознаёт проект по маркеру языка. Он ищет Cargo.toml, go.mod, composer.json, pyproject.toml, setup.py или requirements.txt, двигаясь вверх от каталога, где вы запустили команду.

Если ни одного из них в проекте нет или точка входа лежит в необычном месте, напишите конфиг руками. Он короткий — см. Настройка → Профили.

Шаг 2 — Проверить профиль

Откройте .bugsaur/config.toml и прочитайте его. Именно этот шаг обычно пропускают, и именно он чаще всего ломает первую сессию: init пишет разумное предположение, а не проверенную истину.

Убедиться нужно в двух вещах:

• adapter называет адаптер, который вы действительно поставили;
• program указывает на то, что нужно. Для Rust и C/C++ это собранный бинарник, для Go — каталог пакета, для Python — скрипт, для PHP — каталог проекта.

Шаг 3 — Собрать программу

Для Rust артефакт из program обязан существовать до запуска:

cargo build

Что должно произойти: файл target/debug/app есть на диске.

Go собирает сам Bugsaur, до старта адаптера. У Python и PHP компилировать нечего.

Шаг 4 — Выбрать строку для остановки

Возьмите строку, которая точно выполнится: первая строка main — безопасный выбор. Запомните файл и номер строки, их нужно передать как файл:строка.

Строка должна быть исполняемой, иначе точку останова на ней не удержать. Пустые строки, комментарии и объявления таковыми не являются: адаптер либо перенесёт точку на следующую исполняемую строку, либо откажется её подтвердить.

Шаг 5 — Запустить

bugsaur gui --project . --break src/main.rs:15

Что должно произойти: открывается окно. Недолго видно, как стартует сессия, затем программа выполняется и останавливается. В панели исходника видно ваш файл с отмеченной текущей строкой, остальные панели наполняются данными.

Окно открылось, но ничего не произошло

Откройте панель Logs — Ctrl+L. В ней четыре источника: Program (вывод вашей программы), Session (смены фазы, старт и смерть адаптера, отказы DAP-запросов), Adapter (stderr самого адаптера) и DAP (трасса запросов, выключена по умолчанию как самая шумная).

Включите Session и читайте сверху. Обычно там прямо назван виновник: адаптер, который не смог стартовать, или отклонённый launch.

См. Диагностика → Адаптер не запускается.

Программа отработала целиком и не остановилась

Точка останова не привязалась или привязалась туда, куда программа не дошла. В панели Breakpoints — Ctrl+B — у каждой точки есть кружок, показывающий, что про неё сказал адаптер:

• залитый: адаптер подтвердил;
• жёлтое кольцо: не подтвердил — строка могла оказаться неисполняемой;
• приглушённое кольцо: ответа ещё нет.

См. Диагностика → Точки останова не срабатывают.

Остановилось, но исходник показан не тот или отсутствует

Отладчик и отлаживаемое расходятся в путях. Для всего, что работает в контейнере или на другой машине, это нормально и лечится отображениями путей — см. Диагностика → Исходник не найден.

Шаг 6 — Осмотреться

Вы остановлены. Теперь читайте состояние:

• Variables (Ctrl+V) — всё, что в области видимости, деревом. Разворачивайте структуру через Right или L. Цвет означает вид значения: строки зелёные, числа и bool синие, тип серый в фигурных скобках.
• Call Stack (Ctrl+C) — как исполнение сюда попало. Курсор сразу выбирает фрейм, остальные панели следуют за ним.
• Threads (Ctrl+T) — все потоки, о которых сообщил адаптер.

Панели перебираются по Tab и Shift+Tab либо открываются напрямую: Ctrl+T, Ctrl+C, Ctrl+V, Ctrl+W, Ctrl+E, Ctrl+L, Ctrl+I, Ctrl+B. У активной панели подсвечена вкладка и обведено содержимое.

Шаг 7 — Двигаться

Клавиша	Что делает
F8	шаг с обходом — выполнить строку, остановиться на следующей
F7	шаг внутрь — войти в вызов на этой строке
Shift+F8	шаг наружу — доработать до возврата из функции
F9	продолжить — до следующей точки останова

Сделайте несколько шагов и посмотрите, как меняются значения в Variables.

Шаг 8 — Задать вопрос

Откройте Evaluate (Ctrl+E), нажмите Enter, чтобы войти в поле ввода, и напишите выражение на языке вашей программы. Оно вычисляется в выбранном сейчас фрейме стека, результат появляется ниже.

Чтобы выражение оставалось на экране при каждой остановке, добавьте его в Watches (Ctrl+W). Watches пересчитываются на каждой остановке.

Шаг 9 — Завершить

Нажмите Cmd+F2 (или Ctrl+F2), чтобы завершить сессию, либо просто закройте окно.

Что вы теперь умеете

Вы знаете весь цикл: один раз описать проект, запустить, остановиться, осмотреться, шагать. Всё остальное — подробности.

Куда дальше — зависит от задачи:

• Особенности вашего языка и его адаптера — Языки.
• Каждая панель подробно — Интерфейс отладчика.
• Управление всем этим из редактора — Neovim.
• Готовые рецепты вроде отладки cargo test или PHP внутри Docker — Рецепты.