Repository navigation
User Guide
Looking for a hands-on walkthrough with the 7 bundled MPI showcase programs (
deadlock_ring.cpp,inspection_demo.cpp,collective_mismatch.cpp,ghost_cell_drift.cpp,heap_imbalance.cpp,tag_mismatch_stall.cpp, andsimd_struct_watch.cpp)? See the Hands-On Tutorial (docs/TUTORIAL.md) for step-by-step examples,MemViewDIFF RANKSandEXPORT, offlineman/ Zeal docsets (F1), and thePACKAGE MANAGERdock.

-
Select a Target and Rank Count (
-np):- Pick one of the 7 bundled MPI showcase programs (
inspection_demo (MPI),deadlock_ring (MPI),collective_mismatch (MPI),ghost_cell_drift (MPI),heap_imbalance (MPI),tag_mismatch_stall (MPI),simd_struct_watch (MPI)) or chooseOpen ELF / Binary...in the TARGET dropdown on the main toolbar. - Set the number of MPI processes (
1..64) in the RANKS (-np) spin box.
- Pick one of the 7 bundled MPI showcase programs (
-
Choose a Debugger Backend (
Edit -> Preferences -> Debugger):- Select the local debugger backend in the Debugger Engine dropdown:
GNU GDB (gdb),LLVM LLDB-DAP (lldb-dap),NVIDIA CUDA-GDB (cuda-gdb), orAMD ROCm GDB (rocgdb).
- Select the local debugger backend in the Debugger Engine dropdown:
-
Start the Session (
▶ Run Target):- While idle, only
▶ Run Targetis enabled; stepping and stop buttons remain disabled until a target is running. - Clicking
▶ Run Targetstarts the MPI ranks in the Server Rack panel, pauses Rank 0 atmain, marks the active source line inSourceCodeView, and enables the stepping controls.
- While idle, only
-
Step Instructions (
↷ Step Inst):- Clicking
↷ Step Instadvances the active rank's instruction pointer (rip) and updates the disassembly view, CFG, decompiler, registers, rank status cards, memory view, and source editor together.
- Clicking
-
Stop or Terminate (
■ Stop/✕ Terminate Session):- Ends the debugging session, clears the execution marker, and returns the toolbar to its idle state.
-
Project Explorer (
FILESTab): Right-click inside theFILEStree inProjectExplorerWidgetto create a new source file (New Source File (.cpp)), create a header (New Header File (.hpp)with#pragma once), create a directory (New Folder), rename an entry (F2), or delete a file. Newly created.cppfiles can be registered directly inmeson.buildorCMakeLists.txt. -
Unsaved Buffer Markers & Saving: Edited tabs display a
●prefix (● main.cpp) until saved withCtrl+S(orCtrl+Shift+Sto save all modified tabs). Closing a modified tab prompts to save or discard changes. -
Split Editors & Header/Source Toggle (
F10): Split the editor horizontally (Split Right) or vertically (Split Down) inEditorTabManagerto view two files at once, and pressF10to jump between a.hppheader and its matching.cppimplementation file. -
Scope Breadcrumb Bar & Git Diff Gutter: The bar at the top of the editor shows the current file, struct/class, and function (
File > Class > Function). The right edge of the line-number gutter marks lines added, modified, or deleted relative togit diff.

-
Two-Lane Gutter (
SourceCodeView): The source editor gutter keeps breakpoint markers (●), conditional breakpoint badges (?), and the current execution arrow (▶) in their own column next to the line numbers so they never overlap. - Hover Preview: Moving the cursor over the gutter highlights the line and shows a preview dot where a click will toggle a breakpoint.
-
Conditional Breakpoint Popover (
ConditionalBreakpointDialog): Right-clicking a line in the gutter opens a compact popover next to the cursor:- Line Preview: Shows the line number and the C/C++ statement at that line.
- Rank Filter: Choose All MPI Ranks or Focused Rank Only to control which ranks stop at the breakpoint.
-
clangdAutocomplete: As you type a condition (such asrank == 0ordata[i].), GridLock feeds the expression toclangdat that line in the file so you get completion suggestions for local variables and struct fields. -
Save or Remove: Press
Enter(Done) to apply the condition, or click Remove Breakpoint to delete it.
-
Inline Diagnostics & AST Navigation (
ClangdLspClient):- Diagnostics & Hover: Compiler errors and warnings are underlined directly in the editor, and hovering over a symbol shows its type signature and Doxygen summary.
-
Go to Definition (
F12), Find References (Shift+F12), and Rename (Shift+F6): Jump to a symbol's declaration/definition withF12, list all references in the document withShift+F12, or rename an identifier across the AST without touching comments or string literals withShift+F6.

The bottom dock uses a vertical icon rail on the left to switch between four panel groups:
-
Debug: Shows GDB Console, Memory View, and Evaluator for low-level process inspection. -
MPI: Shows MPI Diagnostics and Package Manager. Inside MPI Diagnostics, a toolbar switches between theDEADLOCK ANALYZERandNETWORK LOGviews, displays a rank summary, and exports diagnostic reports. -
Terminal: Opens the embedded PTY Terminal (QTermWidget). -
Docs: Opens the offline Reference Manual for browsing Zeal docsets and systemmanpages.


The Package Manager tab (HpcConsoleWidget) checks which MPI libraries and development packages are installed on your machine or cluster node:
-
Supported Package Managers: Checks for available backends automatically in order: Spack (
spack), Pacman (pacman), DNF (dnf), APT (apt/dpkg-query), Zypper (zypper), RPM (rpm), and EasyBuild (eb). -
Searching for
"mpi"Packages:- Click
MPIon the bottom tool rail and select the Package Manager tab. - Type
"mpi"into the search box or click Refresh. - Filter by All, Installed Only, or Available, or pick a specific package manager from the Backend dropdown.
- Click
-
Display Modes (
Table|List|Raw):-
Table: Sortable columns (
Package Name,Version,Arch,Source / Repo,Status,Summary) showing installed and available packages (such asopenmpi,mpich,hypre,fftw-mpi, andscalapack). - List: Summary cards showing package name, version, repository, install status, and description.
- Raw: Unformatted command-line output from the underlying package manager.
-
Table: Sortable columns (


- Click Browse / Load Batch Script... or paste a SLURM batch script into the SLURM Batch Script Auto-Detector box in
PreferencesDialog. - GridLock reads
#SBATCHflags (--job-name,--partition,--account,--qos,--nodes,--ntasks,--ntasks-per-node,--cpus-per-task,--gres,--mem,--time,--constraint,--reservation,--chdir,--output,--error) along withmodule loadlines and fills in the cluster launch settings automatically.
- GridLock checks the project directory and runs the matching build tool:
-
Meson (
meson.build): Runsninja -C builddir(andninja -C builddir -t clean). -
CMake (
CMakeLists.txt): Runscmake --build build --parallel(andcmake --build build --target clean). -
GNU Make (
Makefile): Runsmake -j$(nproc)(andmake clean). -
Single MPI Source File: Compiles standalone
.cppor.cfiles withmpicxx -g -O0(falling back tog++ -g -O0).
-
Meson (
-
CODE(Alt+1): Side-by-side C/C++ source editor and disassembly view for source and instruction stepping. -
REVERSE(Alt+2): Hides the source editor and gives the full center area to the split CFG + Decompiler view. -
MPI(Alt+3): Focuses the MPI Diagnostics panel (Deadlock AnalyzerandNetwork Log) and expands the bottom dock. -
Maximize Bottom Dock (
Ctrl+M): Toggles the bottom dock between its normal height and an expanded view when reading long logs or documentation.


-
Jump to Address or Symbol (
Ctrl+G): Type a hex address (0x00401149) or symbol name (sym.main) in the toolbar seek box to jump bothDisassemblyViewandMemViewto that location. -
Cross-References (
X): PressXon an instruction inDisassemblyViewto openXrefInspectorDialogand see incoming callers/branches (XREFS TO) and outgoing calls/jumps (XREFS FROM). -
Patching Instructions & Bytes (
Ctrl+Shift+P/Ctrl+E): Replace instructions inDisassemblyViewor edit raw bytes inMemView, then write out a patched ELF binary viaMainWindow::exportPatchedBinary. -
Offline Documentation (
F1): PressF1on an MPI call (MPI_Init,MPI_Send,MPI_Recv,MPI_Barrier,MPI_Allreduce) or standard C/POSIX function to look up its page in the Reference Manual tab.
Open File -> Attach to Process... (Ctrl+Alt+P) to attach GridLock to a running local Linux process, an active multi-rank MPI job, or a remote gdbserver / QEMU GDB stub.

-
Automatic MPI Job Discovery (
ProcessScanner):- Scans
/proc/<pid>/{comm,cmdline,status,environ,exe}and inspects OpenMPI (OMPI_COMM_WORLD_RANK,OMPI_COMM_WORLD_SIZE), MPICH/Hydra (PMI_RANK,PMI_SIZE), PMIx (PMIX_RANK), and SLURM (SLURM_PROCID,SLURM_JOB_ID,SLURM_NTASKS) environment variables. - Groups sibling MPI ranks under an expandable
MPI Job (N ranks) — <binary>tree header sorted by world rank (Rank 0/4 .. Rank 3/4).
- Scans
-
Whole-Job or Single-Rank Attach:
- Selecting the top-level
MPI Job (N ranks)header and clicking Attach to Selected attaches oneGdbRankCoordinator(-target-attach <pid>) orDapCoordinatorinstance per rank across the job and populates the Server Rack cards. - Selecting an individual rank row or a standalone process attaches only to that PID.
- Selecting the top-level
-
kernel.yama.ptrace_scopeCheck:- When
/proc/sys/kernel/yama/ptrace_scopeis>= 1, Linux blocks non-parentptraceattaches withEPERM. GridLock displays a warning banner at the top of the dialog with a Copy sysctl Fix button that copies:echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
- When

Switch to the Remote Target (gdbserver / QEMU) tab to debug cross-architecture binaries under qemu-user, full-system QEMU VMs, or remote compute nodes running gdbserver:
-
Endpoint Formats (
ProcessScanner::expandRemoteEndpoints):-
Single Target:
localhost:1234or127.0.0.1:2222(Rank 0). -
Multi-Rank Port Range:
localhost:1234..1237expands automatically into 4 rank endpoints (localhost:1234for Rank 0 throughlocalhost:1237for Rank 3). -
Comma-Separated Endpoints:
node0:1234, node1:1234, node2:1234, node3:1234assigns eachhost:portto a sequential MPI rank.
-
Single Target:
-
Local Symbol Binary (ELF) & GDB Binary:
- Point Local Symbol Binary (ELF) to the unstripped ELF binary on your workstation so GridLock loads DWARF source-line mappings, symbols, and CFG blocks before issuing
-target-select. - Pick
gdb,gdb-multiarch,aarch64-linux-gnu-gdb, orriscv64-linux-gnu-gdbin the GDB Binary selector.
- Point Local Symbol Binary (ELF) to the unstripped ELF binary on your workstation so GridLock loads DWARF source-line mappings, symbols, and CFG blocks before issuing
-
Protocol Mode (
remotevs.extended-remote):-
remote (qemu-user -g / gdbserver): Issues-target-select remote <host:port>. Use this forqemu-aarch64 -g 1234 ./guest_binary,qemu-riscv64 -g 1234 ./guest_binary, or standardgdbserver :1234 ./target_binary. -
extended-remote (gdbserver --multi): Issues-target-select extended-remote <host:port>for persistentgdbserver --multisessions.
-
GridLock Repository | Releases | Report an Issue | Roadmap | Accessibility | License (MIT)
Documentation mirrored from docs/ on master.
User Guides
Architecture & Plan
Developer Docs