gdbforge¶
Debug MCU firmware, embedded Linux apps, the Linux kernel and desktop programs from one terminal — one command from target to breakpoint.
GDB stays the debugger. gdbforge is a keyboard-driven, multi-pane front-end around it —
source, the real GDB console, program I/O, threads, call stack and breakpoints on one
screen — and one :lua command brings the target up: it starts OpenOCD, the J-Link GDB
Server, gdbserver over SSH, or kgdb, and attaches.
Built for: Linux desktop applications · applications on embedded Linux boards · the Linux kernel and its modules · firmware on any MCU that OpenOCD or the J-Link GDB Server can reach (bundled bring-up scripts cover STM32 and Zynq MPSoC Cortex-A53/R5).
Install First debugging session User guide
MIT licensed · Linux and macOS, amd64 and arm64 ·
source on GitHub

Cortex-R5 bare-metal firmware over J-Link. :lua r5_baremetal_jlink spawns
JLinkGDBServer, attaches and loads the ELF; then a deep call stack is stepped with the
source, call stack and breakpoint panes updating together.
Watch on YouTube ·
Zynq MPSoC guide ·
samples: examples/stack_demo.c (bare metal),
examples/zephyr_cortex_r5/ (Zephyr, thread-aware) ·
more demos below
Why gdbforge¶
| gdbforge | cgdb | GDB TUI | Vitis / Eclipse | VS Code + Cortex-Debug | |
|---|---|---|---|---|---|
| Terminal-native | Yes | Yes | Yes | No — desktop GUI | No — runs inside VS Code |
| Works over SSH | Yes | Yes | Yes | — | — |
| One-command target bring-up | :lua scripts start OpenOCD, J-Link GDB Server, gdbserver or kgdb, then attach |
No | No | — | — |
| Real GDB console | Yes — :b gdb is the GDB session |
Yes | Yes — it is GDB | — | — |
| Program I/O separate from the debugger | :b io pane, or an external terminal |
No — shares the terminal | No — shares the terminal | — | — |
| Breakpoint, thread and call-stack views | Panes that refresh on every stop | Via GDB commands | No | Yes | Yes |
| Register and memory views | Not yet — GDB commands in the console | Via GDB commands | Register window | Yes | Yes |
| kgdb workflow | :lua kgdb_uart — one UART with kdmx; also two UARTs or Ethernet |
Manual GDB commands | Manual GDB commands | — | — |
| Scriptable | Lua (gdbforge.*); API not frozen yet |
Limited | GDB Python, no UI hooks | — | — |
If you want register and peripheral views today, an IDE is the better fit; if you want plain GDB in a terminal, cgdb and the GDB TUI are smaller and more mature. gdbforge is for terminal users who also want target bring-up, program I/O and list panes in one workspace. More detail: FAQ · full comparison.
Supported workflows¶
| You want to debug | gdbforge gives you | Guide |
|---|---|---|
| A Linux application on your own machine | gdbforge ./prog; output in :b io or an external terminal |
Linux applications |
| An application on a remote or embedded Linux board | :lua remotegdb — scp the binary, start gdbserver over SSH, target remote |
Linux applications |
| STM32 firmware — bare-metal, Zephyr, or FreeRTOS | :lua nucleo_f429zi — ST-Link + OpenOCD or J-Link over SWD, stop at main |
STM32 and Zephyr |
| Zynq UltraScale+ MPSoC Cortex-A53 / Cortex-R5 | :lua r5_baremetal_jlink — J-Link GDB Server or OpenOCD + Digilent HS2 |
Zynq MPSoC |
| The Linux kernel or a loadable module | :lua kgdb_uart — kgdb over one UART with kdmx, two UARTs, or Ethernet |
Kernel and kgdb |
| A Python script, module or pytest test | gdbforge -g py script.py — debugpy over DAP, (py) console evaluates Python in the paused frame |
Python debugging |
| A Go program, including one with its own TUI | gdbforge -g dlv ./prog, :lua dlv_ext_port for a separate terminal |
FAQ — Go and Delve |
Probe and transport support comes from OpenOCD, the J-Link GDB Server, or gdbserver.
gdbforge orchestrates those tools rather than implementing its own probe driver.
Install¶
Requirements: Linux or macOS with a UTF-8 terminal, and gdb (or dlv for Go) on
your PATH. The hello-world below also needs gcc.
Prebuilt binaries are published for Linux and macOS on amd64 and arm64. Replace
the version with the latest release
and pick the file matching your platform.
VERSION=v1.3.0
OS=linux # or: darwin
ARCH=amd64 # or: arm64
curl -fL -o gdbforge \
"https://github.com/yairgd/gdbforge/releases/download/${VERSION}/gdbforge-${VERSION}-${OS}-${ARCH}"
chmod +x gdbforge
sudo mv gdbforge /usr/local/bin/
Each binary ships a matching .sha256 file:
curl -fLO "https://github.com/yairgd/gdbforge/releases/download/${VERSION}/gdbforge-${VERSION}-${OS}-${ARCH}.sha256"
sha256sum -c "gdbforge-${VERSION}-${OS}-${ARCH}.sha256"
go install github.com/yairgd/gdbforge/cmd/gdbforge@latest
Installs into $(go env GOPATH)/bin. Binaries built this way report their version as
dev, because the version string is stamped at release build time.
git clone https://github.com/yairgd/gdbforge.git
cd gdbforge
go build -o bin/gdbforge ./cmd/gdbforge
Building requires the Go version in go.mod
or newer. Use this if you want to edit the bundled
Lua workflow scripts locally.
The Lua workflow catalog and the helper shell scripts (gdbforge --list-scripts) are
embedded in the binary, so :lua r5_baremetal_jlink, :lua remotegdb, :lua kgdb_uart
and the rest work from any of the three installs — no checkout required. Project-local
scripts in ./.gdbforge/lua/ override the embedded ones when you want to customise a
workflow (details).
Check the install:
gdbforge -version
gdbforge --help
Your first debugging session¶
Build a program with debug symbols and open it:
cat > hello.c <<'EOF'
#include <stdio.h>
static int add(int a, int b) { return a + b; }
int main(void) {
int sum = add(2, 3);
printf("hello, gdbforge: %d\n", sum);
return 0;
}
EOF
gcc -O0 -g -o hello hello.c
gdbforge ./hello
gdbforge opens with the source pane and the GDB console (:b gdb) alongside it. From
there:
- Set a breakpoint. Move the cursor to the
int sum = add(2, 3);line with the arrow keys and press Space. The line gets a red marker and the breakpoint appears in the Breakpoints pane. (Equivalent: typebreak mainin:b gdb.) - Start the program. Type
:gdb run. Execution stops on your line and━━▶marks the program counter. Use:gdb run— not c — for the first start; c iscontinue, which GDB rejects until the program is running. - Step. s steps into
add, n steps over, f finishes the current frame, c continues. The Call Stack and Threads panes refresh at every stop. - Inspect. Press i to focus the GDB console and type
print sum— or any other GDB command — then Esc to return to normal mode. - See the program's output.
:b ioshows theprintfoutput in its own pane. - Get help or leave.
:helpopens the in-app manual;:quitor Ctrl-D exits.
Your breakpoints are written to ./.gdbforge/breakpoints.yaml on exit and restored the
next time you start gdbforge from the same directory.
Full key and command reference: User guide · common setup questions: FAQ.
Demos by use case¶
Every screencast below is a recording of a real session. The Cortex-R5 demo is at the top of this page.
Embedded and bare-metal firmware¶
STM32 Nucleo F429ZI — bare-metal, then Zephyr-aware. :lua nucleo_f429zi baremetal
debugs the application on the board over ST-Link and OpenOCD; :lua nucleo_f429zi zephyr
re-attaches with OpenOCD's -rtos Zephyr so Zephyr threads show up in info threads and
in the Threads pane.
Watch on YouTube ·
STM32 and Zephyr guide

Linux applications¶
Program I/O — internal pane versus external terminal. The same program run two ways:
once with its stdout in the built-in :b io pane, and once attached to a real terminal
emulator, which is what full-screen curses programs need.
Watch on YouTube ·
Linux application guide

Linux kernel and modules¶
Kernel kgdb over a single UART. :lua kgdb_uart configures kgdboc, starts kdmx to
split the one serial line into a console PTY and a gdb PTY, opens minicom on the console,
and breaks into kgdb in about two seconds. Then lx-symbols, a breakpoint on a driver's
read path, and cat /dev/… from the console to hit it.
Watch on YouTube ·
Kernel and kgdb guide

Kernel kgdb with two UARTs. When the board has a separate console and kgdb cable there is no mux and no bring-up script — the simplest and most reliable kgdb setup. Watch on YouTube · Kernel guide — two UARTs
Go and Delve¶
gdbforge debugging itself. A gdbforge process attached to another live gdbforge
session through Delve (-g dlv), stepping its own Go code — the same panes and keys as
under GDB.
Watch on YouTube ·
Delve backend details

Project status¶
gdbforge is released and versioned — see the releases page and the changelog. The debugging workflows on this page are used for real work, but the project is maintained by a small number of contributors and parts of it are still moving. A realistic summary:
| Area | State |
|---|---|
| GDB backend — MI2 on a dedicated channel, console, source sync, breakpoints, threads, call stack | Works; the most exercised path |
Delve backend (-g dlv) |
Works for everyday Go debugging, but is not a full peer of GDB: the assembly pane is disabled, and some commands differ (see user guide) |
Program I/O — :b io pane and external terminal |
Works |
Split tree, layouts, modes, : command line with completion, mouse |
Works (provided by termforge) |
Assembly pane (:layout <name> asm, :vs asm) |
Works under GDB only |
Breakpoint persistence (./.gdbforge/breakpoints.yaml) |
Works |
Lua workflow scripts and the gdbforge.* API |
Works — 25 gdbforge.*/pane.* functions and about 30 bundled workflow scripts, all embedded in the binary. The API is not versioned or frozen and may change between releases |
| Tabs | One tab only — no tab bar, no :tabnew |
| Register and memory panes | Not implemented — use :gdb info registers and GDB's x in the console |
| Native OpenOCD backend (telnet/TCL) | Not implemented — OpenOCD is launched as an external GDB server by the Lua scripts |
Planned work and known gaps: roadmap.
More: internals and contributing · built on termforge · releases · issues · CONTRIBUTING.md