Skip to content

Changelog

Release history for gdbforge. Binaries for each version are on the GitHub releases page; see Releasing for how tags drive the builds.

Unreleased

  • Remote Delve on an embedded board (:lua remotedlv) — the Go counterpart of :lua remotegdb: copies the app to the board when its md5 differs, starts headless dlv exec there over SSH, and connects the session. Set where dlv lives on the board with GDBFORGE_REMOTE_DLV (port: GDBFORGE_REMOTE_DLV_PORT, default 2345). Guide: Remote board, Go, including how to cross-build an arm64 dlv and how this differs from C/C++ with gdbserver.
  • -g dlv starts without a program — so a board binary (e.g. arm64 on an x86 PC) is never run locally; load it with :lua remotedlv ./app. -connect host:port attaches to a headless dlv that is already listening.
  • Clear error when the local dlv fails to start — gdbforge used to wait 30 s and report only dlv rpc dial …: connection refused. It now fails as soon as dlv exits and prints Delve's own message (e.g. could not launch process: … no such file or directory or exec format error).
  • Python backend (-g py) — debug Python scripts and modules with gdbforge -g py script.py or gdbforge -g py -- -m module, driving debugpy over DAP (pip install debugpy). Same panes as GDB and Delve: Code arrow, Threads, Call Stack, Breakpoints, program I/O in :b io, and a (py) console where debugger words (b, c, n, s, finish, up, bt, …) win and anything else is Python evaluated in the paused frame. Guide: Debugging Python in the terminal; internals: Debugger integration. --call pkg.mod:func is parsed but not wired yet; no assembly, registers or watchpoints.
  • gdbforge help -mcp — prints how to start -serve, how to connect an agent over REST or MCP, and a ready prompt to give the agent (tools, run-state fields, error codes, usage notes).
  • REST/MCP: reliable run state and run control that waits — the run state now comes from GDB's own *running / *stopped records (a new tracker on the MI channel), not from prompts, and every REST reply carries state (running, stopped, disconnected) with stop_reason, pc, func, file, line and bkpt_number when stopped. New tools: interrupt (waits for the stop, retried once), continue {wait_ms}, wait_for_stop, step, next, stepi, finish, run_to and batch (reads on one halted snapshot, with optional halt/resume). A command that needs a stopped target fails with {"error":"target_running"} instead of raw MI text. API commands now wait for their own reply (MI tokens), which fixes sporadic "unexpected reply" from read_memory on slow targets.
  • gdb_command output is console text by default — with GDB the reply is the joined console and target streams with escapes decoded, or the error message; "format":"mi" returns the old raw MI records and "both" returns both. Behavior change for scripts that parsed the raw reply. MI commands whose answer is in the result record (-data-evaluate-expression) return that payload.
  • list_breakpoints and read_memory — list_breakpoints reads the debugger and adds type, hit count, temporary flag and watchpoints; read_memory adds words32 and endian.
  • Ctrl-C and Space-break while the target runs — GDB prints a prompt after ^running and after every query while the target runs (mi-async); the prompt no longer clears the "inferior running" flag, which made Ctrl-C take the idle path (only "Quit") and Space-break only paint the gutter.
  • Debugger functions are services — the Lua gdbforge.* debugger functions (program, current_file, gdb, gdb_query, dlv_connect, serial_*, uart_send, …) are now defined once as services and installed into Lua, so the same definitions can also be called by the :AI agent and over REST/MCP. Lua call shapes are unchanged (gdb_query still returns out, err, uart_send still takes (dev, [baud,] line)); set_inferior_tty, dlv_connect and spawn_dlv_headless now return their confirmation text instead of printing it.
  • Delve: the UI follows stops after a resume — continue/next/step/stepout/stepi/nexti go over Delve's rpc2 API, which prints no stop banner in the console, so the running flag, Code arrow, Threads and Call Stack stayed on the old state (and stayed empty after the program exited). The end of each resume is now fed to the same parser a console banner goes through.
  • Typed run-control and inspection tools — run_control (continue/next/step/finish/stepi/nexti/run/start/interrupt, waits for the stop and returns {state, file, line}), evaluate, read_memory and registers return small structured results over REST/MCP and from Lua, instead of raw debugger output. read_memory and registers are GDB only; registers returns only the general registers unless you name registers or pass all.
  • -serve ADDR / -serve-token — serve the read-only queries and the :AI tools (including gdb_command) over REST and MCP on a loopback address, so an AI agent can drive the live debug session. Off by default; needs a token (-serve-token T or GDBFORGE_TOKEN=T) that clients send as Authorization: Bearer T; a missing or wrong token gets 401.
  • -inferior-tty external — start with the program's stdio in a new terminal (GDBFORGE_TERMINAL), same as typing :set inferior-tty once the UI is up; also GDBFORGE_INFERIOR_TTY=external. GDB: gdbforge -inferior-tty external -- ./prog. Delve: gdbforge -g dlv -inferior-tty external -- ./prog runs the program under headless dlv in that terminal and connects to it, so Go TUI programs get a real controlling terminal instead of fighting gdbforge for /dev/tty. :set inferior-tty now works in a Delve session too (it used to refuse and point at :lua dlv_ext_port).
  • Enter no longer re-runs continue in the Delve console — Delve repeats the last command on an empty line, and while the target runs the keypress waits in the queue, so after the next stop (breakpoint or Ctrl-C) it resumed again and the console looked hung until the program exited. A bare Enter is ignored while the target runs.
  • Delve UI stays responsive while the target runs — stack/thread/breakpoint reads skip the server while it is running instead of blocking the UI thread; Ctrl-C's halt no longer waits on the server; a second resume while one is in flight is dropped.
  • Break completion outside main — b app.Fo<Tab> completes functions of non-main packages (listed by import path).

v1.3.0

Window management hardened: resizes no longer destroy pane proportions, tiny terminals no longer crash on startup, Ctrl-C reliably halts a running Delve target, and :set inferior-tty hands the external window's terminal to the program being debugged.

Highlights

  • Resize preserves proportions — buildLayout used to write each computed cell count back into Node.Ratio, so every resize replaced the stored proportion with a lossy version of itself; a separator dragged to 0.707 became 0.7035, and a 200x60 → 30x10 → 200x60 round trip moved the code pane from 119x56 to 116x39. Geometry is now a pure function of the ratios and the canvas, so a build is idempotent and a resize reversible. Ratio changes only on Split, DeleteFocus, a separator drag, or applying a named layout.
  • No crash in a small terminal — a split that could not give both sides minPaneCells recorded no geometry, and Draw painted the zero-value canvas anyway, which crashed gdbforge on startup in a 27x8 terminal. Such a split now collapses onto one child, preferring the subtree that holds focus. Draw skips panes without geometry, and TerminalController.Resize rejects a non-positive size at the boundary to xterm-go.
  • The default layout fits 80x20 — all six panes are visible; Threads and Call Stack used to disappear there because clamping had corrupted the ratios.
  • Ctrl-C halts a running Delve target — InferiorRunning was armed by watching bytes typed into the Delve pane, so any resume through Delve's own line editor was invisible to it (history recall sends \x1b[A; a bare Enter repeats the last command and sends nothing). gdbforge now asks the server over rpc2 GetStateNonBlocking, the same query Delve's CLI makes in its SIGINT handler; this also stops a stale flag from making Ctrl-Z suspend gdbforge instead of the target. GDB MI has no equivalent and keeps its existing bookkeeping.
  • Ctrl-C no longer eaten by a stale selection — copy-on-Ctrl-C never cleared the mark, so once live output scrolled the highlight out of view, later presses silently re-copied invisible text. Copying now consumes the selection: the first press copies, the second interrupts.
  • :set inferior-tty gives the pts to the inferior — the external window was held open by a shell that owned the pts as its session's controlling terminal, so GDB's TIOCSCTTY failed with EPERM and the program ran with no controlling terminal. The window is now held by gdbforge re-executed as --hold-inferior-tty, which releases the pts with TIOCNOTTY before advertising the path, so /dev/tty works in there — Go TUIs, curses, getpass. :b io was never affected.
  • Separator drags survive a :layout switch — the resize hook was lost with SetActiveTree; finishLayoutApply now re-wires both it and the status clipboard.
  • Tabs are generic layout containers — a Tab held a *WidgetTree directly and TabWidget carried 28 methods that only forwarded into it, so a tab could never host anything but a split tree. Tab.Content is now a Layout interface (Widget plus BuildLayout), with SplitLayout as the tiling implementation; tab.go drops from 300 lines to 110 and callers take the layout directly.
  • Documentation — window management now states the point it only implied: an internal node is the separator on screen, and only leaves are panes. Three worked cases build it up, including the real default layout dumped from BuildDefault with cell geometry for a 120x40 band.
  • CI on Node 24 — every run warned that checkout@v4, setup-go@v5, setup-python@v5, deploy-pages@v4, and upload-artifact@v4 were being forced onto Node 24 — harmless today, a hard failure once the runners drop Node 20. All actions moved to majors that declare node24.

The split tree, in one sentence

internal node  = a split → no widget, reserves 1 cell for the separator line it draws
leaf node      = a pane  → holds the widget

so: number of splits == number of separators on screen

Upgrading from v1.2.0

  • No breaking CLI changes. Existing .gdbforge/ breakpoints and cmdline history remain compatible.
  • Pane proportions behave differently — on purpose. A separator you drag stays where you put it across resizes. If you relied on a resize quietly re-normalizing a layout, use :layout <name> to reset instead.
  • New internal flag. gdbforge --hold-inferior-tty <path-file> <pid-file> holds the external inferior terminal open; it is an implementation detail, not a user-facing command.
  • Embedders of termforge — TabWidget.ActiveTree(), SetActiveTree(), and the 28 pane forwarders (FocusLeft, VerticalSplit, SetLeafMark, …) are gone. Use TabWidget.Layout() / SetLayout() and call the tree operations on the concrete *SplitLayout, which embeds *WidgetTree. A non-nil tab no longer implies a split tree, so guards must test Layout(), not the container. The named layout presets and internal/demo now build *SplitLayout rather than *WidgetTree.
  • Lua, STM32, and kernel kgdb — unchanged from v1.2.0, including patched kdmx (kdmx -v → 141210a-gdbforge1) for the one-UART path. See Kernel / kgdb.

v1.2.0

Terminal rendering rebuilt on a real xterm emulator, GDB and Delve unified behind one backend API, and an MVC cleanup of the app core — plus STM32 board scripts and a documentation overhaul.

Highlights

  • New terminal pane stack — the old 1100-line Viewport is replaced by a ScrollDocument plus an xterm-backed CompositeTerminal; input, mouse, scroll, and selection each live in their own module. GDB, IO, and exec panes now share one PTY transport (WireTTY) instead of separate console plumbing.
  • Unified backend API — GDB and Delve sit behind a single semantic backend.Backend; controllers call breakpoint, frame, and exec operations instead of formatting MI or Delve CLI strings. Delve runs headless over rpc2.
  • TableWidget — Breakpoints, Threads, and Call Stack moved onto a shared table widget, off Viewport.
  • MVC cleanup — DebuggerApp split into LayoutShell and DebugSession; dlvCtl, luaCtl, exec/IO, and search controllers decoupled behind narrow host interfaces; UI events unified on PostInterrupt → EventBus → controller handlers.
  • GDB console fixes — break-while-running and Ctrl-C after the new-ui mi2 split; Home and End send readline ^A/^E on the prompt line; the view snaps to the bottom on interrupt; wheel and middle-click focus the pane under the pointer.
  • Completion fixes — :lua no longer collides with :b lua, the first Tab enters completion mode, and Delve regained Tab completion and multiclient console behavior.
  • Job control and stability — SIGTSTP is blocked while tcell owns the terminal; Suspend and RunForeground use signal.Reset plus SIGTSTP directly; the terminal is restored when gdb or dlv is missing at startup; the macOS build is restored.
  • STM32 board catalog — new :lua stm32-stlink <board|mcu> [profile] plus STM32F405 ST-Link and J-Link SWD scripts, and a Zephyr thread-switching fix. Profiles: baremetal, zephyr, freertos.
  • Lua catalog reorganized — scripts grouped under lua/mpsoc/, lua/stm32/, lua/kernel/, and lua/embedded/. :lua command names are unchanged.
  • Flow browser — new cmd/flowdoc tool discovers and generates an execution-path catalog, published as a searchable flow browser on the docs site.
  • Serial backend — the custom internal/serial package is replaced by go.bug.st/serial.
  • Documentation — a FAQ, STM32 and MPSoC guides, demo GIFs on the platform pages, public YouTube links, and the documented FreeRTOS profile; several inaccurate probe and kgdb claims corrected.

Terminal pane refactor at a glance

before:  Viewport (scrollback + ANSI + selection + input, 1137 lines)
after:   ScrollDocument      — scrollback, search, selection
         CompositeTerminal   — xterm emulation (gitpod-io/xterm-go)
         WireTTY             — one PTY transport for GDB / IO / exec
         TableWidget         — Breakpoints / Threads / Call Stack

Upgrading from v1.1.0

  • No breaking CLI changes. Existing .gdbforge/ breakpoints and cmdline history remain compatible.
  • Lua script paths moved. If you copied scripts out of the repo, re-copy from the new locations (lua/mpsoc/, lua/stm32/, lua/kernel/, lua/embedded/). Project-local .gdbforge/lua/ still wins over the embedded catalog, and :lua names are unchanged.
  • STM32 — prefer the generic :lua stm32-stlink <board|mcu> [baremetal|zephyr|freertos]; per-board aliases (nucleo_f429zi, stm32f405_stlink, stm32f405_jlink) still work. See STM32 debug.
  • Kernel kgdb — unchanged from v1.1.0, including patched kdmx (kdmx -v → 141210a-gdbforge1) for the one-UART path. See Kernel / kgdb.
  • Delve — now started headless with rpc2; for Go programs with their own full-screen UI use :lua dlv_ext_port (alias dlv_port) so program stdio stays in that window.

v1.1.0

Kernel kgdb automation, a Lua REPL, Assembly UI improvements, and expanded documentation, building on the v1.0.0 multi-pane GDB/Delve TUI.

Highlights

  • Kernel and module debugging (kgdb) — first-class Lua workflows for Linux kernel debug from :b gdb:
    • :lua kgdb_uart — one shared UART plus kdmx: configures kgdboc, starts kdmx, opens minicom, sysrq break-in, and target remote in about two seconds
    • :lua kgdb_net — Ethernet kgdb (target remote over TCP)
    • :lua kgdb_serial and :lua kgdb_trigger — in-process UART mux for one-cable setups, with a semi-automatic owner switch
    • Two-UART manual path — console on one cable, GDB on another; no mux and no Lua script required
    • kgdb mode — lighter post-stop refresh on serial, CLI n/s/c, and attach-stack and clean :q! fixes
  • Lua REPL pane — interactive gdbforge.* REPL with API help and tab completion.
  • Assembly view — cgdb-style per-function dumps, ?? windows, and stable scroll; Call Stack click-after-scroll fix; CellStyle rendering instead of generated ANSI.
  • Ctrl-C / Ctrl-Z / Ctrl-D routing — split into Activity and Confirm routers for clearer interrupt handling.
  • Docs site — MkDocs site under docs/ (./docs/serve.sh), with a Mermaid lightbox and zoom toolbar.
  • Process hygiene — spawned children (kdmx, minicom, terminals) are killed when gdbforge exits.
  • Screencasts — updated README kernel demo (:lua kgdb_uart); the two-UART workflow is preserved in Kernel / kgdb.

Kernel kgdb quick start

export GDBFORGE_KGDB_UART=/dev/ttyUSB0
export GDBFORGE_KGDB_VMLINUX=/path/to/vmlinux
export GDBFORGE_KGDB_MODULES=/path/to/kernel-source

./bin/gdbforge -g gdb
# then:
:lua kgdb_uart
# stopped in kgdb — lx-symbols, break, continue, cat /dev/… from minicom

Full write-up: Kernel / kgdb. Script catalog: lua/README.md.

Upgrading from v1.0.0

  • No breaking CLI changes. Existing .gdbforge/ breakpoints and cmdline history are compatible.
  • Kernel workflows are optional Lua scripts — copy lua/kgdb_* into .gdbforge/lua/ or use the embedded catalog.
  • For :lua kgdb_uart, use patched kdmx (kdmx -v → 141210a-gdbforge1). Build from agent-proxy at commit 468fe4c and apply tools/kdmx-gdbforge.patch — see building kdmx.

v1.0.0

First tagged 1.0 of gdbforge: a Vim-inspired multi-pane terminal front-end for GDB and Delve.

Highlights

  • Multi-pane workspace — Code, GDB/dlv console, IO, Threads, Call Stack, Breakpoints, and Assembly.
  • Layouts — :layout wide, panels, default, and classic; splits (:vs and :split); :only.
  • Vim-like UX — Normal, Insert, Command, Search, Completion, and Lua modes; the : cmdline; focus chords.
  • GDB and Delve — -g gdb|dlv, a shared session, safer breakpoint insert while running, and conditional breakpoints.
  • Mouse and clipboard — selection, middle-click paste, and double-click on a status name to copy the full path.
  • Persistence — breakpoints and cmdline history under .gdbforge/.
  • Lua automation — embedded catalog plus project and home scripts; :lua jobs cancellable with Ctrl-C; games, remotegdb, and Cortex-R5 J-Link bring-up.
  • AI / MCP — same-process tools on the live session (:AI).
  • Host skeleton — cmd/demo reuses the TUI framework without a debugger.
  • Docs and release — in-app :help, the docs site, and tag-driven multi-arch binaries.