Neovim: Installation¶

The Lua source frontend lives in lua/bugsaur/init.lua in the repository you already cloned. There is nothing separate to download.

Wire it in¶

lazy.nvimPlain runtimepath

{
  dir = "/absolute/path/to/bugsaur",
  name = "bugsaur",
  config = function()
    require("bugsaur").setup({
      binary = "/absolute/path/to/bugsaur/target/debug/bugsaur",
      gui = true,
    })
  end,
}

vim.opt.rtp:prepend("/absolute/path/to/bugsaur")

require("bugsaur").setup({
  binary = "/absolute/path/to/bugsaur/target/debug/bugsaur",
  gui = true,
})

After editing your config, restart Neovim — or :source $MYVIMRC and call setup again.

binary points at the built debugger, so bugsaur does not have to be installed globally on PATH.

`gui = true` versus `gui = false`¶

The flag decides who opens the debugger window.


`gui = true`	Neovim launches the window itself. Recommended — no separate terminal needed.
`gui = false`	You run the debugger yourself and Neovim connects to it as a source frontend.

Window options¶

Four options, all off by default, all describing the project's window rather than a language or a session — which is why they live here and not in a profile:

require("bugsaur").setup({
  gui = true,
  gui_focus_on_stop = true,  -- the window raises itself on every stop
  auto_attach = true,        -- on Neovim start, attach to an already open window
  gui_theme = "light",       -- window theme, if the project did not name one
  gui_width = 1200,           -- initial width, if the project did not name one
  gui_height = 800,           -- initial height, if the project did not name one
  gui_layout = {             -- panel layout, if the project did not name one
    left = 0.3,
    bottom_left = { "Call Stack" },
    bottom = {},
  },
})

Option	Default	What it does	When it is read
`gui_focus_on_stop`	`false`	the window comes forward on each stop	when the GUI process starts
`auto_attach`	`false`	silently return to the project's running session	on every `setup()` call
`gui_theme`	`nil`	window theme when the project did not choose	when the GUI process starts
`gui_width`	`nil`	initial window width when the project did not choose	when the GUI process starts
`gui_height`	`nil`	initial window height when the project did not choose	when the GUI process starts
`gui_layout`	`nil`	panel layout when the project did not choose	when the GUI process starts

\"When it is read\" is where the confusion comes from

Five of these are read when the GUI process starts. Changing them in init.lua and re-sourcing does nothing to a window that is already open — the new value applies to the next window.

The project wins over the editor¶

gui_theme, gui_width, gui_height and gui_layout apply only when the project has said nothing. A [ui] section in .bugsaur/config.toml takes precedence, because it is shared by everyone who opens that project. Details: Configuration → UI.

Execution highlighting¶

On a stop, the plugin opens the current source location, places the ▶ execution sign and highlights the whole stop line with the BugsaurExecutionLine group — by default a link to CursorLine.

Breakpoint signs have three states: pending ○, verified ●, rejected ⊗.

Turn the line highlight off, or point it at a different group:

require("bugsaur").setup({
  execution_line = false,
  -- execution_line_hl = "DiagnosticInfo",
})

Verify¶

Open a project, put the cursor on an executable line and run:

:ToggleBreakpoint
:DebugStart

If :DebugStart is not a known command, setup() did not run — check the path in dir or in rtp:prepend.

Next: Quick Start.