ImGui front end for cmake --debugger communicating with DAP.
Allows stepping through and inspecting a CMake build. Supports at least
Windows, macOS, Linux, and Cygwin/MSYS2.
On any platform:
$ cmake -B build
$ cmake --build build
Linux distributions may need xorg-dev or libwayland-dev. File dialogs
(Ctrl+O, Set Working Directory) use kdialog or zenity, tried in that
order. The Cygwin/MSYS2 build has a native Win32 GUI but expects to debug
a non-native CMake, i.e. uses POSIX system interfaces and paths.
By default dependencies are downloaded automatically, currently:
- Dear ImGui (docking branch)
- nlohmann/json
- GLFW (except on Windows)
Source releases bundle dependencies in deps/ for offline builds.
Distribution packagers can use system libraries instead:
$ cmake -B build -DDEPS=LOCAL
The DEPS variable controls how nlohmann/json and GLFW are resolved:
| Value | Behavior |
|---|---|
FETCH (default) |
bundled → downloaded |
LOCAL |
system find_package only |
On Linux, use GLFW 3.5 or later. With older GLFW, dcmake hangs on Wayland while its window is hidden, such as on another workspace, and configuring warns about it.
Dear ImGui is always bundled or downloaded because no distributions package the docking branch. To produce a source release tarball with bundled dependencies:
$ cmake -P cmake/SourceRelease.cmake
Which runs git archive, downloads dependencies into the tree, and
produces a self-contained dcmake-VERSION.tar.gz.
$ dcmake [cmake args..]
Where all arguments become CMake arguments in the debugger. The command
line is editable within UI and supports shell variable expansion ($VAR
on Unix, %VAR% on Windows). The debugger can handle configuration (-B,
-S) and scripts (-P). For example, to step through building a source
release:
$ dcmake -P cmake/SourceRelease.cmake
Then press F10 to begin stepping from the first line of the script.
| Key | Action |
|---|---|
| F5 | Start (free-running) / Continue |
| Shift+F5 | Stop |
| Ctrl+Shift+F5 | Restart |
| F10 | Start (break at first line) / Step Over |
| F11 | Start (break at first line) / Step In |
| Shift+F11 | Step Out |
| F9 | Toggle breakpoint on current line |
| Ctrl+F | Find in source |
| F3 / Shift+F3 | Next / previous match |
| Enter / Shift+Enter | Next / previous match (while in find bar) |
| Escape | Close find or go-to-line bar |
| Ctrl+G | Go to line |
| Ctrl+O | Open file |
-
Run to line: right-click a source line and select "Run to line" to continue execution up to that line
-
Variable hover tooltips: hover over a variable name in the source view to see its current value
-
Search filters: on variable panels (Locals, Cache Variables, Targets, Tests); case-insensitive substring match on name or value
-
Breakpoint drift mitigation: breakpoints track their line content so they survive file edits between runs
-
Watch window: pin variables for monitoring across steps; bare names search Locals then Cache, use
$CACHE{VAR}to target cache explicitly -
Persistent layout and state: window positions, panel visibility, breakpoints, and watch expressions are saved across sessions
Layout and window state are saved to imgui.ini in a platform config
directory:
| Platform | Path |
|---|---|
| Linux/macOS | $XDG_CONFIG_HOME/dcmake/ or ~/.config/dcmake/ |
| Windows | %XDG_CONFIG_HOME%/dcmake/, %HOME%/.config/dcmake/, or %AppData%\dcmake\ |
CMake's DAP debugger inconsistently normalizes paths on case-insensitive
filesystems (macOS HFS+, Windows NTFS). When a path differs between
DAP client and the command line — e.g. a breakpoint set on Test.cmake
while CMake was invoked with cmake -P test.cmake — the breakpoint may
not trip. So debugging older CMake builds, use the canonical path case in
command line arguments and includes.
If dcmake is abruptly stopped on a non-Windows host, the CMake debuggee may get stuck in an infinite loop, requiring manual cleanup.
Both issues were fixed in CMake 4.4.0.