Repository navigation
Installation and Building
GridLock (v0.8.7) runs on x86_64 Linux systems under both native Wayland compositors (Niri, Sway, Hyprland, KDE Plasma, GNOME) and X11/XWayland servers. You can run a standalone AppImage from GitHub Releases or compile from source with Meson and Ninja.
Each release on GitHub Releases ships two self-contained AppImage editions:
-
GridLock-0.8.7-x86_64.AppImage(Lite Edition): Bundles thegridlockbinary, Qt6 Wayland (libqwayland*.so,wayland-decoration-client,wayland-graphics-integration-client,wayland-shell-integration) and XCB (libqxcb.so,xcbglintegrations,libxcb-cursor.so.0) platform plugins,libqtadvancedcss,qtermwidget6color schemes and keyboard layouts, and SQLite3 docset drivers without tutorial binaries. -
GridLock-0.8.7-Tutorials-x86_64.AppImage(Tutorials Edition): Includes everything in the Lite Edition plus all 8 MPI tutorial source files and pre-compiled debug binaries underusr/share/gridlock/tutorial/.
chmod +x GridLock-0.8.7-Tutorials-x86_64.AppImage
./GridLock-0.8.7-Tutorials-x86_64.AppImage-
Wayland and X11 Selection:
AppRunconfiguresQT_PLUGIN_PATH="$APPDIR/usr/plugins"andusr/bin/qt.conf. When bothWAYLAND_DISPLAYandDISPLAYare active andQT_QPA_PLATFORMis unset,AppRunexportsQT_QPA_PLATFORM="wayland;xcb"so Qt6 connects over Wayland first and falls back to X11/XCB if needed. On native (non-WSLg) Wayland compositors,src/main.cppsetsQT_WAYLAND_DISABLE_WINDOWDECORATION=1. -
Running Without
libfuse2: On containers or minimal hosts without FUSE, extract and run on the fly:./GridLock-0.8.7-x86_64.AppImage --appimage-extract-and-run # or export APPIMAGE_EXTRACT_AND_RUN=1 -
External Host Tools Used at Runtime: The AppImage bundles the GUI and Qt6 runtime. Host debugging, compilation, and LSP features invoke tools from your system
PATHwhen present:gdb(orgdb-multiarch,lldb-dap,cuda-gdb,rocgdb),mpirun/mpiexec,mpicxx/mpicc/g++,objdump(binutils),clangd, andman.
GridLock requires a C++23 compiler (GCC 13+ or Clang 16+), Meson >= 1.1, Ninja, CMake (when building Qt-Advanced-Stylesheets or qtermwidget6), Qt6 (Core, Gui, Widgets, Network, Sql, Concurrent, Svg, OpenGLWidgets, Qml, Test), qtermwidget6, tomlplusplus (auto-fetched via external/tomlplusplus.wrap if absent), and an MPI implementation (OpenMPI or MPICH).
sudo pacman -S --needed \
base-devel gcc clang meson ninja cmake pkgconf git \
qt6-base qt6-declarative qt6-svg qt6-tools qt6-wayland \
qtermwidget tomlplusplus sqlite \
openmpi gdb lldb binutils elfutils man-db zeal patchelf xcb-util-cursorsudo apt update
sudo apt install -y \
build-essential g++ clang clangd cmake meson ninja-build pkg-config git \
qt6-base-dev qt6-base-dev-tools qt6-tools-dev qt6-tools-dev-tools \
qt6-declarative-dev qt6-wayland qt6-wayland-dev \
libqt6sql6-sqlite libqt6svg6-dev libqtermwidget6-dev libsqlite3-dev \
openmpi-bin libopenmpi-dev gdb gdb-multiarch lldb llvm binutils elfutils \
libxcb-cursor0 libxcb-cursor-dev patchelf man-dbNote for
qtermwidget6on older Debian/Ubuntu releases: Iflibqtermwidget6-devis not in your APT repositories, buildlxqt-build-tools(2.0.0) andqtermwidget(2.0.1) from source with-DCMAKE_INSTALL_PREFIX=/usr(see.github/workflows/release.ymlfor exact commands).
sudo dnf install -y \
gcc-c++ clang clang-tools-extra cmake meson ninja-build pkgconf-pkg-config git \
qt6-qtbase-devel qt6-qtdeclarative-devel qt6-qtsvg-devel qt6-qttools-devel qt6-qtwayland-devel \
qtermwidget-qt6-devel tomlplusplus-devel sqlite-devel \
openmpi openmpi-devel gdb lldb binutils elfutils man-db zeal patchelf xcb-util-cursorOn Fedora, load the OpenMPI environment module into your shell before building or launching MPI targets if mpicxx and mpirun are installed under /usr/lib64/openmpi/bin:
export PATH="/usr/lib64/openmpi/bin:${PATH}"(GdbRankCoordinator and MainWindow::ensureTargetBinaryCompiled also search /usr/lib64/openmpi/bin, /usr/lib/openmpi/bin, /usr/lib64/mpich/bin, and /usr/lib/mpich/bin directly.)
GridLock links against Qt-Advanced-Stylesheets (libqtadvancedcss). If QtAdvancedStylesheets is not installed system-wide via CMake package config, compile the bundled submodule once:
git clone --recurse-submodules https://github.com/bnorthern42/GridLock.git
cd GridLock
cmake -S external/Qt-Advanced-Stylesheets \
-B external/Qt-Advanced-Stylesheets/build \
-GNinja -DQT_VERSION_MAJOR=6 -DCMAKE_BUILD_TYPE=Release
ninja -C external/Qt-Advanced-Stylesheets/buildmeson setup builddir
ninja -C builddirThis builds two default targets in builddir/:
-
builddir/gridlock: Main workstation executable (configured withbuild_rpathpointing toexternal/Qt-Advanced-Stylesheets/build/lib). -
builddir/mpi_mm: Debug MPI matrix-multiplication binary compiled fromtutorial/mpi_mm.cviampicc -g -O0.
Launch GridLock directly from the build directory:
./builddir/gridlock-
Local System Install (
scripts/build_local.sh): Configuresbuild/, compiles with Ninja, and runssudo meson install -C build(installsgridlock,data/gridlock.desktop, and the512x512hicolor application icon). -
Uninstall (
scripts/uninstall_local.sh): Runssudo ninja -C build uninstall. -
Build Local AppImages (
scripts/build_appimage.sh):# Build both Lite and Tutorials AppImages into /tmp: OUTPUT_DIR=/tmp bash scripts/build_appimage.sh # Build only the Lite AppImage: bash scripts/build_appimage.sh --lite --output-dir /tmp # Build only the Tutorials AppImage: bash scripts/build_appimage.sh --with-tutorials --output-dir /tmp # Populate AppDir/ and run the ldd / plugin verification gate without mksquashfs: bash scripts/build_appimage.sh --appdir-only
-
Build Ext4 Toolpak Image (
scripts/build_toolpak.sh): Creates a 512 MB ext4 loop imageGridLock.toolpakpopulated viaDESTDIRinstall frombuilddir/.
GridLock compiles any selected tutorial/*.cpp target on demand with mpicxx -g -O0 when you click ▶ Run Target or ⚙ Build (Ctrl+B). To compile all 7 primary C++ showcase programs and the 5 auxiliary C/C++ demos manually from a terminal:
# 7 primary C++ MPI showcase programs (listed in the toolbar TARGET dropdown)
for prog in inspection_demo deadlock_ring collective_mismatch ghost_cell_drift \
heap_imbalance tag_mismatch_stall simd_struct_watch; do
mpicxx -g -O0 "tutorial/${prog}.cpp" -o "tutorial/${prog}"
done
# 5 auxiliary C/C++ tutorial programs (used by --tutorial-mode and manual labs)
mpicc -g -O0 tutorial/deadlock_demo.c -o tutorial/deadlock_demo
mpicc -g -O0 tutorial/mpi_mm.c -o tutorial/mpi_mm
mpicxx -g -O0 tutorial/register_demo.cpp -o tutorial/register_demo
mpicxx -g -O0 tutorial/memview_demo.cpp -o tutorial/memview_demo
mpicxx -g -O0 tutorial/memview_diff_demo.cpp -o tutorial/memview_diff_demoSee Tutorials Walkthrough for line-by-line instructions on reproducing and inspecting each bug.
| Option | Description |
|---|---|
-v, --version
|
Prints gridlock 0.8.7 to stdout and exits 0 before initializing Qt/GUI plugins. |
-h, --help
|
Prints command-line usage options and exits 0. |
--help-all |
Prints GridLock options plus standard Qt6 command-line flags. |
--tutorial-mode |
Opens the modal Interactive Tutorials launcher (TutorialDialog) before mapping MainWindow. |
--test-mode [file] |
Runs GridLockAutomationRunner. If [file] is supplied, compiles it with mpicc/mpic++ -g -O0 to /tmp/<name>_test_demo and starts a 2-rank session. |
--verbose |
Enables [DEBUG] and [INFO] diagnostic messages on stderr. |
--headless |
Runs under QT_QPA_PLATFORM=offscreen without showing the splash screen or raising a desktop window. |
--snapshot <file> |
Renders MainWindow offscreen, saves a PNG screenshot to <file>, and exits (0 on success, 1 on error). |
| Variable | Effect |
|---|---|
WAYLAND_DISPLAY / DISPLAY
|
Inspected at startup to select Wayland vs. X11/XCB, or fall back to offscreen in headless containers. |
QT_QPA_PLATFORM |
Overrides the Qt platform plugin (wayland, xcb, wayland;xcb, offscreen). |
GRIDLOCK_LIVE_WAYLAND |
When non-empty, keeps native Wayland active even when --headless or --snapshot is passed. |
GRIDLOCK_TEST_CONFIG_DIR |
Redirects ConfigManager's global config.toml directory (used by isolated unit tests). |
GRIDLOCK_MEMTRACK_SO |
Path to the compiled heap-caller interposition shared library (/tmp/gridlock_memtrack_v2_<uid>.so) injected via LD_PRELOAD into GDB-launched ranks when Track Heap Callers (LD_PRELOAD) is enabled in MemoryProfilerWidget. |
SHELL |
Default login shell executed inside TerminalDockWidget (falls back to /bin/bash). |
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