Repository navigation
Architecture
GridLock organizes its debugging and binary inspection panels into four dock and splitter regions inside MainWindow:
flowchart TD
MW["MainWindow"]
TB["Top Zone: MainToolbar + AddressNavToolbar (ELF Section Ribbon)"]
LEFT["Left Dock Area: ProjectExplorerWidget (FILES | SYMBOLS | STRINGS)"]
CENTER["Center Stage: MasterHorizontalSplitter (EditorTabManager + DisassemblyView)"]
BOTTOM["Bottom Console Zone: Tool-Window Icon Rail + Grouped Sub-Tabs"]
RIGHT["Right Dock Area: Variables | Registers | Watch Expressions | Server Rack"]
STATUS["Bottom Status Bar: Architecture | Active MPI Rank | PC/Seek | Session Status"]
MW --> TB
MW --> LEFT
MW --> CENTER
MW --> BOTTOM
MW --> RIGHT
MW --> STATUS
Dock widgets and bottom console tabs share a consistent layout managed by ThemeManager and MainWindow::harmonizeBottomConsoleTabs():
- Header Bar: Each panel has a top bar containing its title, view mode buttons, and filter inputs.
- Content Area: Tables, trees, text editors, and canvas views sit inside the panel without nested frames or redundant scrollbars.
-
Bottom Tool Rail: A vertical icon strip on the left side of the bottom dock groups the seven bottom panels into four modes (
Debug:GDB Console,Memory View,Evaluator;MPI:MPI Diagnostics,Package Manager;Terminal:Terminal;Docs:Reference Manual).
To keep compilation fast and individual files easy to navigate, UI and backend subsystems are split into focused translation units. TestMainWindowUI::testFullRepoGoogleStyleAndDocumentation() checks that .cpp and .hpp files across src/ and tests/ stay under the project's size ceiling (< 950 lines per file) and include header guards (#pragma once), @file/@brief headers, and Doxygen comments.
| Subsystem | Translation Units | Responsibility |
|---|---|---|
| MainWindow |
src/ui/MainWindow.cppsrc/ui/MainWindowWorkspace.cppsrc/ui/MainWindowNavigation.cppsrc/ui/MainWindowDocks.cppsrc/ui/MainWindowDebugger.cppsrc/ui/MainWindowCohesion.cpp
|
Window lifecycle and rank slots (MainWindow.cpp), dock/splitter/toolbar setup (MainWindowWorkspace.cpp), address navigation (MainWindowNavigation.cpp), detachable docks (MainWindowDocks.cpp), stepping and breakpoint handlers (MainWindowDebugger.cpp), and theme updates, project build runner, and screenshot capture (MainWindowCohesion.cpp). |
Source Editor, Tabs & clangd LSP |
src/ui/EditorTabManager.cppsrc/ui/views/SourceCodeView.cppsrc/ui/dialogs/ConditionalBreakpointDialog.cppsrc/core/utils/ClangdLspClient.cpp
|
Multi-tab and split-pane editor management, dirty buffer tracking, and header/source switching (EditorTabManager.cpp), editor gutter, Git diff indicators, inline diagnostics, and scope breadcrumbs (SourceCodeView.cpp), conditional breakpoint popover (ConditionalBreakpointDialog.cpp), and JSON-RPC 2.0 clangd completion, diagnostics, hover, definition, references, and rename (ClangdLspClient.cpp). |
| Project Explorer & Binary Inspector |
src/ui/widgets/ProjectExplorerWidget.cppsrc/core/utils/ElfBinaryInspector.cppsrc/core/utils/MemoryBoundsValidator.hppsrc/core/utils/MiSanitizer.cpp
|
File tree CRUD operations (New File, New Folder, Rename, Delete), build file registration, and ELF symbol/string tables (ProjectExplorerWidget.cpp), ELF64/DWARF parsing and binary patching (ElfBinaryInspector.cpp), memory read bounds checks (MemoryBoundsValidator.hpp), and GDB/MI command sanitization (MiSanitizer.cpp). |
| MPI Diagnostics & Package Manager |
src/ui/widgets/MpiDiagnosticsWidget.cppsrc/ui/widgets/HpcConsoleWidget.cpp
|
Deadlock Analyzer and Network Log views (MpiDiagnosticsWidget.cpp), plus Spack/Pacman/DNF/APT/Zypper/RPM package search across Table/List/Raw modes (HpcConsoleWidget.cpp). |
| Disassembly, CFG & Decompiler |
src/ui/views/DisassemblyView.cppsrc/ui/views/DisassemblyAnalysis.cppsrc/ui/views/DisassemblyDecompiler.cpp
|
Linear assembly view (DisassemblyView.cpp), basic-block splitting, CFG edge routing, rank badges, minimap, and cross-references (DisassemblyAnalysis.cpp), and Approx C/C++/Pseudocode decompilation (DisassemblyDecompiler.cpp). |
| Themes, Config & Preferences |
src/core/managers/ThemeManager.cppsrc/core/managers/ConfigManager.cppsrc/ui/dialogs/PreferencesDialog.cppsrc/ui/dialogs/PreferencesDialogPages.cpp
|
Semantic ThemePalette tokens across 12 dark and light themes (ThemeManager.cpp), TOML and QSettings persistence including the debugger backend engine (ConfigManager.cpp), and Preferences pages including the #SBATCH script importer (PreferencesDialog.cpp, PreferencesDialogPages.cpp). |
| UI Integration Tests |
tests/test_ui.cpptests/test_ui_aux.cpptests/test_ui_cohesion.cpptests/test_ui_debugger.cpp
|
Core widget and layout tests (test_ui.cpp), file CRUD, Git diff gutter, debugger engine, CFG/decompiler, style, and screenshot tests (test_ui_aux.cpp), ELF64/Xrefs/theme palette tests (test_ui_cohesion.cpp), and split editor, dirty tab, breakpoint, LSP, tool-rail, and package-manager tests (test_ui_debugger.cpp). |
Views stay synchronized through Qt signal/slot connections set up in MainWindowWorkspace.cpp, MainWindowDebugger.cpp, and MainWindowCohesion.cpp:
-
Source <-> Disassembly Sync:
- Clicking a line in
SourceCodeViewemitsSourceCodeView::sourceLineSelected(int lineOneBased), which looks up the corresponding instruction address viaMainWindow::sourceLineToAddress(lineOneBased)and jumpsDisassemblyView(linear, CFG, and decompiler) andMemViewto that address. - Clicking an instruction or basic block in
DisassemblyViewemitsDisassemblyView::addressSelected(uint64_t addr), which updatesMemViewand highlights the matching source line viaMainWindow::addressToSourceLine(addr)inSourceCodeView.
- Clicking a line in
-
Editor Tabs, Splits &
clangdLSP:- Modifying text in
SourceCodeViewemitsmodificationStateChanged(bool), which updates the●dirty tab prefix inEditorTabManagerand refreshes theFile > Class/Struct > Functionscope breadcrumb bar. - Right-clicking line
NinLineNumberAreaopensConditionalBreakpointDialognext to the gutter dot and consumes theQContextMenuEventso the default text editor menu does not open on top of it. As the user types a condition,ClangdLspClient::buildVirtualCompletionDocumentsplices the expression into lineNof an in-memory buffer and requeststextDocument/completionresults fromclangd.
- Modifying text in
-
Stepping Workflow (
startTargetWorkflow/stepInstructionWorkflow/stopTargetWorkflow):- Starting or stepping a target advances the active rank's program counter via
DisassemblyView::nextInstructionAddress, refreshes the rank cards inServerRackView, updatesRegisterView(rip,rsp,rbp,rax,eflags), scrollsMemView, and moves the current-line arrow inSourceCodeView.
- Starting or stepping a target advances the active rank's program counter via
-
Watch Promotion & Context Menus:
- Promoting a variable from
VariablesDockWidgetor an expression fromExpressionEvaluatorWidgetemitswatchExpressionRequested(const QString&), which adds a column toDifferentialGrid(Watch Expressions). - Context menu actions in
DisassemblyViewandRegisterView(Show in Memory View,Open Xrefs Inspector (X),Lookup Documentation (F1)) jump directly toMemView,XrefInspectorDialog, andReferenceManualWidget.
- Promoting a variable from
GridLock Repository | Releases | Report an Issue | Roadmap | Accessibility | License (MIT)
Documentation mirrored from docs/ on master.
User Guides
Architecture & Plan
Developer Docs