Installation

There are two things to install: Bugsaur itself and at least one debug adapter for the language you work in. Prebuilt archives are the normal installation path; building from source remains available for development.

Install a release

Open GitHub Releases and download the archive for your machine:

Platform	Archive name
Linux x86-64	bugsaur-v0.1.0-Linux-X64.tar.gz
macOS on Intel	bugsaur-v0.1.0-macOS-X64.tar.gz
macOS on Apple Silicon	bugsaur-v0.1.0-macOS-ARM64.tar.gz

Each archive contains bugsaur, the bundled php-dbgp-adapter, and the optional Neovim frontend under lua/. Extract it and put the binaries on your PATH:

tar -xzf bugsaur-v0.1.0-macOS-ARM64.tar.gz
cd bugsaur-v0.1.0-macOS-ARM64
mkdir -p "$HOME/.local/bin"
install -m 755 bugsaur "$HOME/.local/bin/bugsaur"
install -m 755 php-dbgp-adapter "$HOME/.local/bin/php-dbgp-adapter"

Use the filenames of the release you downloaded; v0.1.0 above is only an example.

Build from source

git clone https://github.com/real420og/bugsaur.git
cd bugsaur
make build

The binary lands in target/debug/bugsaur. Copy or symlink it into a directory on your PATH to call it as bugsaur.

Build through make, not through a bare cargo

The Makefile resolves the toolchain directory from rust-toolchain.toml and puts it first on PATH. A stray older cargo — a Homebrew one, for instance — would otherwise silently change the result.

Verify the binary works:

bugsaur

With no arguments it prints its usage and exits with status 2. That output is the confirmation that the binary is in place.

Install an adapter

Adapters are resolved through PATH, so they must be visible to the debugger.

Rust, C, C++GoPythonPHP

Install CodeLLDB and make sure the codelldb binary is on PATH:

command -v codelldb

If it came from Mason:

export PATH="$HOME/.local/share/nvim/mason/bin:$PATH"

Install Delve:

go install github.com/go-delve/delve/cmd/dlv@latest
command -v dlv

debugpy is a Python module, so it is installed into the interpreter that runs your code — usually the project virtualenv, not the system Python:

python3 -m pip install debugpy      # or: .venv/bin/pip install debugpy
python3 -m debugpy --version

PHP needs no external adapter. A release archive includes php-dbgp-adapter next to bugsaur; make build produces the same pair in target/debug. Put their directory on PATH so the adapter catalog can find it:

export PATH="$PWD:$PATH"                # extracted release archive
export PATH="$PWD/target/debug:$PATH"   # source build

On the PHP side you need Xdebug configured — see Languages → PHP.

Install the Neovim plugin

Optional. Bugsaur works without it; the plugin adds source navigation and breakpoint UX on top.

The Lua source frontend lives in lua/bugsaur/init.lua and connects to the backend over a Unix socket. Release archives include the complete lua/ directory, so their extracted directory can be passed directly to lazy.nvim:

{
  dir = "/absolute/path/to/bugsaur-v0.1.0-macOS-ARM64",
  name = "bugsaur",
  config = function()
    require("bugsaur").setup({
      binary = "/absolute/path/to/bugsaur-v0.1.0-macOS-ARM64/bugsaur",
      gui = true,
    })
  end,
}

For a source checkout, keep dir pointed at the repository and use target/debug/bugsaur as the binary instead.

setup() only carries editor and window options. Adapters, programs and launch arguments live in the project config, not here. Full reference: Neovim → Installation.

Verify the installation

Check	Command	Expected
Debugger	bugsaur	usage text, exit status 2
Rust / C / C++	command -v codelldb	a path
Go	command -v dlv	a path
Python	python3 -m debugpy --version	a version
PHP	command -v php-dbgp-adapter	a path
Neovim	:DebugStart exists	command completes in Neovim

If a command -v check prints nothing, the adapter is not on PATH — that is the single most common reason a session fails to start. See Troubleshooting → Adapter fails to start.

Next

Quick Start — describe your project and open the window.