Custom adapters¶

Anything with a DAP adapter can be debugged with Bugsaur. Adding one means writing a catalog entry — no changes to the debugger.

Add an adapter¶

Create ~/.config/bugsaur/adapters.toml:

[adapters.mylang]
id = "mylang"
command = "mylang-dap"
args = ["--stdio"]
transport = "stdio"

Then use the id in a profile:

[profiles.app]
adapter = "mylang"
program = "src/main.ml"

Your entries are merged on top of the built-in catalog by id: a new id adds an adapter, an existing one replaces the built-in entry.

To keep a catalog inside a project instead, point at it explicitly:

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

--adapters replaces the search of the two config locations; the built-in catalog is still the base.

Choosing a transport¶

stdio — Bugsaur starts the adapter and talks over its stdin and stdout:

transport = "stdio"

tcp — the adapter listens and Bugsaur connects. Bugsaur picks a free port and substitutes it into tcp_argument:

tcp_argument = "--listen={host}:{port}"
transport = { tcp = { host = "127.0.0.1" } }

{host} and {port} are the substitutions available there.

Defaults for the request body¶

launch_arguments in a catalog entry gives defaults for every profile using that adapter, which the profile can then override:

[adapters.mylang.launch_arguments]
stopOnEntry = false
console = "internalConsole"

Building before launch¶

If programs for this adapter need compiling, describe it:

[adapters.mylang.build]
command = "mylangc"
args = ["-g", "-o", "{out}", "{program}"]

{out} is the binary Bugsaur expects to receive; {program} is what the profile's program names. The result goes to <root>/.bugsaur/build/.

Leave build out and Bugsaur builds nothing — the adapter gets program as-is.

Adapters that are slow to start¶

When the delay is a property of the adapter rather than of a project, put the timeout in the catalog:

[adapters.mylang]
id = "mylang"
command = "mylang-dap"
transport = "stdio"
launch_timeout = 300

Precedence is profile → catalog → 120 seconds.

Running without a profile at all¶

For a one-off you can skip the project config entirely:

bugsaur gui \
  --adapter codelldb \
  --program /absolute/path/to/program \
  --cwd /absolute/path/to/dir \
  --launch-arguments '{"stopOnEntry": true}'

Flag	What it does
`--adapter <id>`	which catalog entry to use
`--program <path>`	what to debug
`--cwd <path>`	working directory; defaults to the current directory here, since there is no project root
`--launch-arguments <json>`	the DAP request body, as JSON
`--adapters <path>`	which catalog to read

This mode reads no project config, which also means no [ui] section — the theme and layout then come from the command line or the defaults.

When a new adapter does not work¶

Turn on the DAP category in the Logs panel and read the exchange. Since Bugsaur does not interpret adapter-specific fields, a rejected launch is almost always the adapter objecting to the body it received — the error text comes from the adapter itself and usually names the offending key.