Quick Start¶

The shortest path from a project you already have to a debugger window.

1. Describe what to debug¶

Run this in the root of your project:

bugsaur init

It looks up the tree for a language marker — Cargo.toml, go.mod, composer.json, or pyproject.toml / setup.py / requirements.txt — and writes .bugsaur/config.toml.

The generated file is a starting point, not a guess. It shows up in git status and is meant to be edited by hand:

version = 1
default = "app"

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

Each profile says what to debug with which adapter. Relative paths resolve from the project root.

The config belongs to the project, not to the editor

bugsaur from a terminal and :DebugStart from Neovim read the same file, so a profile you fix once is fixed for both.

2. Open the window¶

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

The window opens, the adapter starts, the program runs and stops at line 15.

The --project flag points at any directory inside the project; the root is the nearest directory up the tree that contains .bugsaur/. Pick a profile with --profile <name>, otherwise default is used.

Rust builds nothing for you

program for Rust points at a build artifact. If it does not exist yet the launch fails with program is not readable. Build first:

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

Go builds automatically; Python and PHP have nothing to build.

3. Debug¶

Once stopped, the window shows the stack, the threads and the variables in scope. The execution keys:

Key	Action
`F9`	continue
`F8`	step over
`F7`	step into
`Shift`+`F8`	step out
`Cmd`+`F2` / `Ctrl`+`F2`	stop

F1 or ? shows the bindings actually in effect, after all configuration layers have been applied.

Every panel is explained one at a time in Debugger UI.

Without a project config¶

You can skip the config entirely and name everything on the command line:

bugsaur gui \
  --adapter codelldb \
  --program /absolute/path/to/program \
  --break /absolute/path/to/source.rs:20

This is useful for a one-off. Note that with no project there is no root, so the working directory becomes the directory you launched from.

Next¶

Your First Debug Session — the same path, but slowly, with what to expect at each step and what to do when it does not happen.