Debug Adapter Protocol (IDE debugging)

copperline-ctl --dap is a Debug Adapter Protocol server: VS Code, nvim-dap and any other DAP client can debug a program running in Copperline with source-level breakpoints and stepping, the register file, locals and globals, memory, the custom chipset, reverse execution and a Debug Console, without a GDB in between.

The adapter is a client of the control protocol, like the MCP mode. It launches an emulator with --run PROG (windowed by default, so the Amiga’s screen stays live beside the editor) or attaches to one started with --control-info, and turns each DAP request into control protocol calls. Source lines, symbols, variables and call frames come from the program’s own debug information, relocated by the hunk addresses the guest reports when it loads the program.

copperline-ctl --dap                 # on stdin/stdout, how IDEs spawn adapters
copperline-ctl --dap-listen :4711    # over TCP (a "debugServer" connection)
copperline-ctl --dap --info /tmp/ccp.json   # launch/attach both use this session

VS Code¶

For installation, executable paths, a complete launch configuration, and screenshots, start with the VS Code guide. Package and install tools/vscode-copperline as a VSIX; it contributes the copperline debug type and runs copperline-ctl --dap from your PATH. The settings copperline.ctlExecutable and copperline.emulatorExecutable name the two executable files when they are elsewhere (a source build’s target/release/copperline-ctl and target/release/copperline, or the copies every release package ships; see Command-line tools for where each package puts them). A launch configuration:

{
  "type": "copperline",
  "request": "launch",
  "name": "Run hello in Copperline",
  "program": "${workspaceFolder}/hello",
  "model": "A1200",
  "fast": "8M",
  "entryPoint": "main",
  "stopOnEntry": true
}

F5 opens a Copperline window, warp-boots to the program, and stops at its entry point with the source open; breakpoints, Step Over/Into/Out, Step Back, the Variables view, hovers, the Disassembly view, the memory viewer and the Debug Console all work from there. Stop closes the window.

While the program is paused, the debug toolbar’s Profile button captures one emulated frame and Profile (Multi) prompts for a frame count. The adapter sends the custom copperline/profile {"frames": N} request, derives a compact live unwind table from the session’s DWARF, captures precise instruction samples, converts them to a source-mapped .cpuprofile, and opens the result in VS Code. The profile contains optimized inline frames and a [Bus wait] child that isolates time lost to chip-DMA contention. Other DAP clients can send the same custom request and open the returned path.

The same toolbar can open Copperline’s native Debugger, Console, and Frame Analyzer windows without reimplementing them in a webview. The Debug sidebar’s Custom Registers tree is fed by the adapter’s Chipset scope; hovering a register shows its shared access, chipset, and bit-field documentation. The command palette also provides Init Amiga Project, Convert EXE to ADF, and Profile File Size. The project template detects Bartman’s installed toolchain through amiga.bin-path, or can select bebbo amiga-gcc or vbcc/vasm.

Other clients¶

nvim-dap, with the adapter on stdio:

local dap = require("dap")
dap.adapters.copperline = { type = "executable", command = "copperline-ctl", args = { "--dap" } }
dap.configurations.c = {
  { type = "copperline", request = "launch", name = "Run in Copperline",
    program = "${workspaceFolder}/hello", stopOnEntry = true, entryPoint = "main" },
}

Any client that connects to a TCP debug server can use --dap-listen ADDR instead. Zed loads debug adapters through extensions only; none exists yet.

Launch and attach¶

launch starts copperline --control-gui :0 --control-info FILE --run PROGRAM (with --control and --noaudio when headless is true) and connects to it. The emulator boots the bundled AROS ROM, or whatever the configuration says. Arguments:

attach connects to a running emulator through controlInfo (the --control-info file) or address + token, and takes program, symbolFile, sourceMap, entryPoint and stopOnEntry the same way. When the program is already running, its segments are matched against the file and the symbols relocate at once; otherwise a loadseg break waits for the guest to load it.

Behind a launch, the control server arms a one-shot loadseg stop for the program before the first frame runs (the same break-at-entry --gdb has), so the boot cannot outrun the adapter. At that stop the adapter reads the program’s segments with segments.list, relocates its debug information, binds the breakpoints the client set while the program was not loaded yet, and runs to the entry point.

Debug information¶

The adapter reads the executable itself and, optionally, an ELF sibling. What each toolchain provides:

Keep the ELF used by elf2hunk alongside the hunk executable, or name it explicitly with symbolFile. For example, a relocatable build can use:

m68k-amiga-elf-gcc -g -O0 -r -nostdlib main.c worker.c -o program.elf
elf2hunk program.elf program

The adapter applies the ELF’s debug-section relocations before reading DWARF, including references between compilation units’ abbreviation and line tables. Source breakpoints set before LoadSeg are initially unverified; they bind and emit a breakpoint changed event when the program loads. Selecting DWARF 4 instead of 5 still requires applying these relocations.

A fully linked ELF built with -Wl,--emit-relocs is also supported. That option retains relocation records for tools such as elf2hunk; its debug contents are already resolved by the linker. The adapter preserves those contents without applying the retained relocations again. --emit-relocs is not needed for -r output, which already carries pending relocations.

Locals need -O0: the adapter evaluates the single-operation DWARF locations (DW_OP_fbreg, DW_OP_breg, DW_OP_reg, DW_OP_addr, DW_OP_call_frame_cfa) and shows anything else as unsupported rather than guessing. Values render by type: integers, characters, booleans, floats, pointers (with the string behind a char *), arrays and structs expand in the Variables view. Without DWARF the Globals scope lists the data and BSS symbols as longs.

The console line printed at launch says what was found: 19 hunk symbols; DWARF from the executable's debug hunk: 3 function(s), 43 line row(s), 5 global(s), call-frame info.

What maps to what¶

A stop from a breakpoint the debugger window set, or from a catch, reg watch, beam trap or Copper breakpoint set through !break.add, is reported as a breakpoint with the machine’s description. In a windowed session a pause or resume made from the window is noticed within a second and reflected in the IDE.

Limitations¶

• Locals are shown for simple location expressions and one level of struct/array nesting; optimised code, location lists and DWARF expressions render as unsupported.

• One thread (the CPU) is presented; Exec tasks are not separate threads.

• The sourceMap is a prefix replacement; when a recorded path does not exist on the host, the adapter also tries the path’s tail under the program’s directory.

• Restart re-launches the emulator with the same arguments.