Repository navigation
Developer Architecture and Testing
github-actions[bot] edited this page Nov 20, 2026
·
2 revisions
GridLock is written in C++23 (-Wall -Wextra -Wpedantic) on Qt6 and Meson, with a hard architectural ceiling of < 950 lines per source and header file.
GridLock/
├── meson.build # Build definition: gridlock, mpi_mm_bin, and 22 test suites
├── external/
│ ├── Qt-Advanced-Stylesheets/ # Submodule providing dynamic SVG/QSS theming (libqtadvancedcss)
│ └── tomlplusplus.wrap # Meson wrap fallback for toml++ 3.4.0
├── resources/ # Qt .qrc bundles (icons, Nerd Font glyphs, base stylesheets)
├── scripts/ # Packaging, UI screenshot capture, coverage, and Wiki sync scripts
├── tutorial/ # 8 primary C++ MPI showcase targets + 5 auxiliary C/C++ demos
├── tests/ # QtTest unit, protocol, security, and offscreen UI suites
└── src/
├── main.cpp # CLI fast-path, Wayland/QPA setup, splash, and mode dispatch
├── RankState.hpp # Per-rank execution, frame, watch, and register telemetry model
├── backend/ # GridLockAutomationRunner (--test-mode) and TestGenerator
├── core/
│ ├── commands/ # IDebugCommand implementations (Launch, Continue, Step, Pause, etc.)
│ ├── hpc/ # Coordinators, ProcessScanner, DeadlockAnalyzer, Memory & Sanitizer
│ ├── managers/ # Config, Session, Shortcut, Theme (with QSS cache), Docset, Spack
│ ├── models/ # VariableNode and lazy-expanding VariableTreeModel
│ └── utils/ # CliParser, ElfBinaryInspector, and ClangdLspClient
└── ui/
├── MainWindow*.cpp # Split across 7 cohesive translation units (< 950 lines each)
├── EditorTabManager.* # Multi-tab and horizontal/vertical split editor coordinator
├── GdbConsoleWidget.* # 60 FPS coalesced GDB/MI console with readline history, Ctrl+R, Tab complete
├── dialogs/ # AttachProcess, ConditionalBreakpoint, CommandPalette, ProgrammerCalculator, ArrayPlot, PointerGraph, SignalCatchpoint, Checkpoint, Preferences, Xref
├── docks/ # VariablesDockWidget, CallStackDockWidget, TerminalDockWidget
├── shaders/ # Precompiled SPIR-V GLSL 450 heatmap shaders (reserved for v0.8.8)
├── tutorial/ # TutorialDialog (--tutorial-mode)
├── views/ # SourceCodeView, DisassemblyView, MemView, MemoryProfiler, ServerRack
└── widgets/ # DifferentialGrid, MpiDiagnostics, MpiNetworkLog, HpcConsole, ReferenceManual
IBackendCoordinator defines a backend-agnostic Qt signal/slot contract implemented by two coordinators:
-
GdbRankCoordinator(GdbRankCoordinator.hpp,GdbRankCoordinator.cpp,GdbRankInspection.cpp):-
Local MPMD Launch: Allocates
/tmp/gridlock_mi_<pid>_<seq>/r<i>.{in,out}named pipes (mkfifo,0600,O_RDWR | O_NONBLOCK) and launches onempirunjob with:-separated-np 1GDB/MI3 clauses. -
Local Attach (
attachToProcesses): Spawns onegdb --interpreter=mi3instance per selectedProcessEntrysorted bympiRank, sends-target-attach <pid>, syncs cached breakpoints, and detaches cleanly via-target-detachon session stop. -
Remote Stubs (
attachToRemoteTargets): Spawnsgdborgdb-multiarch, loads local DWARF info via-file-exec-and-symbols, and connects via-target-select remote <endpoint>or-target-select extended-remote <endpoint>. -
Execution Control, Breakpoints, Signals, Catchpoints & Checkpoints: Supports
nexti(-exec-next-instruction),Run to Cursor(-exec-until),Jump(-exec-jump),Force Early Return(-exec-return), non-destructive-break-enable/-break-disable, temporary-break-insert -t,rbreak,-break-commands,handle <SIG>/info handle(token210),completetab completion (token211), copy-on-writecheckpoint/info checkpoints/restart/delete checkpoint(tokens212and213), client-side{ident}logpoints, hardware watchpoints (-break-watch [-r|-a]), and Process Record (record full).
-
Local MPMD Launch: Allocates
-
DapCoordinator(DapCoordinator.cpp):- Speaks JSON-RPC 2.0 (
Content-Lengthframing) tolldb-dap(orlldb-vscode), mapping 0-basedrankIdto 1-based DAPthreadId, supportinglaunch,attach,setBreakpoints(condition,hitCondition,logMessage),dataBreakpointInfo/setDataBreakpoints,stackTrace,scopes,variables,evaluate,readMemory(withNativeMemoryReaderfast path for reads> 1024doubles), andstepBack/reverseContinue.
- Speaks JSON-RPC 2.0 (
-
CommandPaletteDialog: Subsequence fuzzy scorer acrossShortcutManageractions (>), cached workspace files,clangd/ELF symbols (@), themes, and live MPI ranks (#). -
ProgrammerCalculatorDialog: ModelessQt::Windowbase converter (HEX/DEC/OCT/BIN, IEEE-754 float/double,8/16/32/64-bitwidth,BSWAP, 64-bit interactive bit-toggle grid, radix-aware keypad) wired to right-click selection handoff signals across all major inspection views. -
ArrayPlotDialog: Modeless 1D line/stem and 2D colormapped heatmap canvas (Viridis,Plasma,Cool-Warm,Grayscale) with IEEE-754NaN/Inftelemetry, auto-refresh previous-stop ghost curve diffing, CSV/PNG export, andgnuplotoutput. -
SignalCatchpointDialog: Two-tab manager for POSIX/HPC signal dispositions (handle <SIG>) and C++ exception, Linux syscall, anddlopen/dlclosecatchpoints. -
CheckpointDialog: Modeless copy-on-write snapshot manager pairing GDBcheckpoint/restart/delete checkpointwithinspectProcessCheckpointSafety(pid, procRoot)scanning<procRoot>/<pid>/fdraw symlink targets (::readlink) and<procRoot>/<pid>/mapsVMAs forSafe,Warning, andBlockedOrUnsafehandles.
-
QSS Disk Cache (
ThemeManager): Compiled theme stylesheets fromQt-Advanced-Stylesheetsare hashed and cached on disk under~/.cache/gridlock/qss/so warm launches skip SVG/QSS recompilation and apply the cached stylesheet directly. -
Deferred Bottom-Tab Initialization: Hidden bottom-rail tabs (
Package Manager,Terminal, andReference Manual) avoid spawningQTermWidgetPTY shells, queryingspack/dnf/pacman, or scanning Zeal SQLite3 docsets during startup; each initializes lazily on first tab activation or explicit API call (F1docset lookup,Build Target). -
Non-Blocking
clangdStartup:ClangdLspClientlaunches asynchronously after the main window paints so interactive window startup stays under450 ms(verified ingridlock_ui_tests).
-
ProcessScanner: Parses/proc/[pid]/{comm,status,cmdline,exe,environ}(recognizingOMPI_*,PMI_*,PMIX_*,SLURM_*, andMV2_*rank/world/job variables), checks/proc/sys/kernel/yama/ptrace_scope, and expands single, range (../-), and comma-separatedRemoteTargetSpecendpoints. -
DeadlockAnalyzer: Inspects frames0..7across paused ranks for 16 canonical MPI calls (9collectives +7P2P/wait calls and theirPMPI_*wrappers), classifying multi-rank stalls intoCollective DivergenceorWait-For Cycle Stalland resolving user C/C++ caller frames. -
NativeMemoryReader,MemoryBoundsValidator,MemoryDiffer,MemoryExporter: Wraps Linuxprocess_vm_readvbehind overflow-checked bounds (>= 0x1000,<= 64 MiB, natural stride alignment), computes byte-level cross-rank diff masks, and exportsInt32/Float/DoubleCSV matrices or raw.binfiles. -
MiSanitizer&TelemetryObfuscator: Rejects embedded NULs, nesting depth> 32, shell metacharacters (;,|,&,`,$), multi-line smuggling, and GDB shell-escape commands (!,shell,pipe,make), whileTelemetryObfuscatorshapes telemetry into constant-rate1400-byte frames at20 Hz(50 msticks). -
ElfBinaryInspector&ClangdLspClient: Zero-dependency ELF64 section/symbol/string parser +objdump -d -l -C -M intelDWARF mapper +/procmemory/CPU parser, paired with an asynchronous JSON-RPC 2.0clangdclient (completion,publishDiagnostics,hover,definition,references,rename).
To keep every file under < 950 lines while maintaining fast incremental builds, MainWindow is partitioned by responsibility:
-
MainWindow.cpp: Construction, menu bar, preferences application, and window close lifecycle. -
MainWindowWorkspace.cpp: Toolbar, address navigation ribbon, central editor/disassembly splitters, right-side docks, andViewmenu. (Note:HpcConsoleWidget.cppis unity-included at the bottom ofMainWindowWorkspace.cpp.) -
MainWindowDocks.cpp: Bottom tool rail (Debug,MPI,Terminal,Docs), lazy bottom-tab activation, floating dock drag/redock handlers, andThemePalettepropagation. -
MainWindowDebugger.cpp:Debugmenu action wiring, non-linear execution workflows (nexti,Ctrl+F10, PC jump, early return,rbreak), floating dialog launchers (ArrayPlotDialog,SignalCatchpointDialog,CheckpointDialog), target compilation (ensureTargetBinaryCompiled), workspace switching, and build system detection. -
MainWindowExecution.cpp: Live coordinator signal wiring, local/procattach, remotegdbserver/QEMU attach,MemView/MemoryProfilerWidget/PointerGraphDialogintegration, inline ghost values, and reverse debugging workflows. -
MainWindowNavigation.cpp: BidirectionalsourceLineToAddress/addressToSourceLinemapping, history back/forward stack, andCtrl+Shift+Fworkspace search. -
MainWindowCohesion.cpp: Compact<= 26pxbottom-tab layout normalization,F1documentation lookup, and deterministic screenshot generation (captureDocumentationScreenshots).
Delete stale .gcda coverage counters (if coverage was previously enabled) and run all 22 suites headlessly:
find builddir -name "*.gcda" -delete
meson test -C builddir --print-errorlogsEvery test target in meson.build runs with QT_QPA_PLATFORM=offscreen:
| # | Suite Name | Executable | Scope Tested |
|---|---|---|---|
| 1 | coordinator_tests |
gridlock_tests |
GdbRankCoordinator, ProcessScanner (/proc & remote endpoint ranges), DeadlockAnalyzer
|
| 2 | lsp_tests |
gridlock_lsp_tests |
ClangdLspClient completion, diagnostics, hover, definition, references, rename |
| 3 | ui_tests |
gridlock_ui_tests |
57 offscreen end-to-end UI tests across MainWindow, docks, Command Palette, Calculator, Array Plotter, Pointer Graph, Signals/Catchpoints, GDB Readline, Non-Linear Execution, Breakpoint Lifecycle, CoW Checkpoints, and startup QSS caching |
| 4 | config_tests |
gridlock_config_tests |
ConfigManager and SessionManager TOML / QSettings round-trips |
| 5 | docset_tests |
gridlock_docset_tests |
DocsetManager SQLite3 Zeal .docset indexing and man lookup |
| 6 | dap_parser_tests |
gridlock_dap_parser_tests |
DAP Content-Length framing and JSON event parsing |
| 7 | dap_commands_tests |
gridlock_dap_commands_tests |
DAP next, stepIn, continue, pause, and reverse execution requests |
| 8 | dap_breakpoints_tests |
gridlock_dap_breakpoints_tests |
DAP setBreakpoints, conditions, and dataBreakpointInfo watchpoints |
| 9 | dap_stacktrace_tests |
gridlock_dap_stacktrace_tests |
DAP threads and 64-frame stackTrace unwinding |
| 10 | dap_variables_tests |
gridlock_dap_variables_tests |
DAP scopes, variables, and VariableTreeModel lazy expansion |
| 11 | dap_evaluate_tests |
gridlock_dap_evaluate_tests |
DAP evaluate (watch and repl contexts) |
| 12 | dap_lifecycle_tests |
gridlock_dap_lifecycle_tests |
DAP initialize, launch, attach, SLURM scancel, and disconnect
|
| 13 | dap_memory_tests |
gridlock_dap_memory_tests |
DAP readMemory base64 decoding |
| 14 | hpc_memory_tests |
gridlock_hpc_memory_tests |
NativeMemoryReader (process_vm_readv) and MemoryDiffer
|
| 15 | stride_security_tests |
gridlock_stride_security_tests |
MemoryBoundsValidator overflow, null-page, alignment, and 64 MiB guards |
| 16 | dap_native_bridge_tests |
gridlock_dap_native_bridge_tests |
Hybrid DAP + NativeMemoryReader large-buffer fast path |
| 17 | sanitizer_tests |
gridlock_sanitizer_tests |
MiSanitizer metacharacter, control-byte, nesting-depth, and smuggling rejection |
| 18 | obfuscator_tests |
gridlock_obfuscator_tests |
TelemetryObfuscator 1400-byte MTU padding and 50 ms chaff timing |
| 19 | advanced_features_tests |
gridlock_advanced_features_tests |
ElfBinaryInspector, MemoryProfilerWidget, PointerGraphDialog, logpoints |
| 20 | memory_export_tests |
gridlock_memory_export_tests |
MemoryExporter typed CSV (Int32, Float, Double) and raw .bin output |
| 21 | mi_parser_tests |
gridlock_mi_parser_tests |
GDB/MI3 tuple/list parsing, @entry filtering, and C++ access-specifier unwrapping |
| 22 | cliparser_tests |
gridlock_cliparser_tests |
CliParser flag parsing and shouldUseOffscreenPlatform detection |
-
Run a Single
QtTestSlot ingridlock_ui_tests:QT_QPA_PLATFORM=offscreen ./builddir/gridlock_ui_tests testWorkstationUiCohesionAndIntegratedDocViewer
-
Generate HTML Line/Branch Coverage (
scripts/run_coverage.sh):bash scripts/run_coverage.sh # Writes builddir/meson-logs/coveragereport/index.html via gcovr -
Regenerate All 21 Documentation Screenshots (
scripts/capture_ui.sh): Normalmeson testruns never modifydocs/screenshots/. To regenerate all screenshots deterministically (using sanitized/procfixtures forattach_process.pngandattach_remote.png):bash scripts/capture_ui.sh
-
Dry-Run GitHub Wiki Synchronization (
scripts/sync_wiki.sh): Mirrorsdocs/*.mdanddocs/screenshots/*.pnginto a flat GitHub Wiki checkout with rewritten links,Home.md,_Sidebar.md, and_Footer.md:bash scripts/sync_wiki.sh /tmp/gridlock-wiki-preview
GridLock Repository | Releases | Report an Issue | Roadmap | Accessibility | License (MIT)
Documentation mirrored from docs/ on master.
Getting Started
User Reference
- Keyboard Shortcuts
- UI & Debugging Manual
- MPI Diagnostics & HPC
- Memory, RE & Profiling
- Configuration & Themes
Internals & Plan