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.
Related project: termforge¶
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.