Skip to content

Internals and contributing

How gdbforge is built and how to work on it. If you only want to debug something, start from the home page and the user guide instead.

Developer documentation

The architecture — the MVC split, controllers and host interfaces, the event bus, and the repository layout — is documented separately:

Page What is in it
Overview Goals, motivation, and how gdbforge compares to cgdb and the GDB TUI
Architecture Subsystems and data flow. Start with MVC, built on termforge, and the design principles
PTY architecture Dual PTY master/slave, GDB versus Delve, :b io, external terminal
Debugger integration GDB MI2, the unified backend.Backend, the Delve backend, :AI / GdbMcpService
Window management The three-band root layout, split trees, tabs, command line
Directory structure Repository layout and the responsibility of each package
Dependencies Go modules and the import rules between the debugger and the framework
Developer guide Onboarding, which files to read in what order, common pitfalls
Flow browser Curated call trees (Tab completion, Ctrl-C, the stop pipeline) with links to source. Has its own search box, separate from this site's header search
Roadmap · Releasing · Hosting Planned work, how releases are cut, how these docs are built

The generic terminal UI machinery — the widget system, the rendering pipeline, and the split-tree engine — lives in termforge and is documented on its own site: UI architecture · rendering · window management.

Mermaid diagram sources live under docs/diagrams/.

Reading these docs locally

python3 -m pip install -r requirements-docs.txt
./docs/serve.sh          # or: task docs

Then open http://127.0.0.1:8765/. Details: Hosting.


gdbforge is the debugger. The terminal UI it runs on is a separate project, termforge — widgets, split-tree windows, tabs, colon commands with tab completion, key-sequence bindings, and the terminal emulator pane, with no debugger in it. termforge was extracted from gdbforge once that machinery stood on its own, so gdbforge is both its origin and its largest consumer. This repository is now the debugger only.

Question Site
How do I debug something with GDB, Delve, an embedded target, or kgdb? This site
How does a widget, split tree, or :command work in general? termforge documentation — UI architecture, window management, rendering
How do I build my own terminal app on the same framework? termforge documentation
How does gdbforge drive GDB or Delve? Debugger integration on this site

Source: github.com/yairgd/termforge · how the split works: ARCHITECTURE.md — Built on termforge.

Contribution workflow: CONTRIBUTING.md · issue tracker.