CMake Debugging Guide
*********************
This guide explains how to attach a debugger to CMake's unit testing framework.
We'll focus on using **GDB** on Linux for both command-line and IDE debugging.
See documentation on `CMake Development`_ for more information.
.. _`CMake Development`: README.rst
Linux: Using GDB
================
On Linux, the GNU Debugger (**GDB**) is the standard tool for debugging the
CMake test suite. The core process involves launching the ``cmake`` executable
from within GDB with a specific set of arguments that configure and run the
desired test.
GDB Configuration
-----------------
For effective debugging, GDB must be configured to handle child processes
correctly, which CMake tests often create. A good practice is to use a local
``.gdbinit`` file in your build directory. This keeps CMake-specific settings
separate from your global configuration.
**1. Enable Local .gdbinit Files (One-Time Setup)**
To allow GDB to automatically load configuration from your build directory,
add the following line to your global GDB initialization file at
``$HOME/.gdbinit``. This is a one-time setup that makes future projects easier
to manage.
.. code-block:: text
set auto-load local-gdbinit on
**2. Create a Project-Specific .gdbinit**
Next, create a ``.gdbinit`` file inside your CMake **build directory**.
This file will contain settings specific to debugging CMake.
To make this easier, you can symlink the template file provided in the CMake
source tree:
.. code-block:: bash
# Navigate to your build directory
cd /path/to/your/cmake/build
# Create a symlink to the template
ln -s $cmake_srcdir/Utilities/gdb/gdbinit-template .gdbinit
The template contains the essential settings for debugging CMake tests:
.. code-block:: gdb
# Allows GDB to follow child processes
set follow-fork-mode child
# Allows the parent process continue in parallel
set non-stop on
Debugging from the Command Line
-------------------------------
To start debugging, first cd to the build directory. Then, launch the
``cmake`` executable using ``gdb --args``, which passes the necessary test
configuration arguments directly to CMake.
.. note::
To get the launch command, run ``ctest -R "RunCMake.$TESTNAME" -VV -N``
The following example runs the ``InstallPackageInfo`` test.
.. code-block:: bash
# Define paths to your CMake source and build directories
CMAKE_SOURCE_DIR="$HOME/cmake"
CMAKE_BUILD_DIR="$CMAKE_SOURCE_DIR/build"
# Define the specific test to run
TEST_NAME="InstallPackageInfo"
# Navigate to the build directory
cd "$CMAKE_BUILD_DIR"
# Launch GDB with the appropriate arguments for the test
gdb --args ./bin/cmake \
"-DCMAKE_MODULE_PATH=$CMAKE_SOURCE_DIR/Tests/RunCMake" \
"-DRunCMake_GENERATOR=Ninja" \
"-DRunCMake_SOURCE_DIR=$CMAKE_SOURCE_DIR/Tests/RunCMake/$TEST_NAME" \
"-DRunCMake_BINARY_DIR=$CMAKE_BUILD_DIR/Tests/RunCMake/$TEST_NAME" \
"-P" "$CMAKE_SOURCE_DIR/Tests/RunCMake/RunCMakeTest.cmake"
Once GDB loads, you may set breakpoints (e.g., ``b cmInstallCommand``) and
then start the test by typing ``run``.
Filtering Tests
---------------
Some test suites contain multiple sub-tests. To run only a specific one,
you can use the ``RunCMake_TEST_FILTER`` environment variable.
For example, to run only the "Metadata" test within the ``InstallPackageInfo``
suite, you can set the variable before launching GDB:
.. code-block:: bash
RunCMake_TEST_FILTER="Metadata" gdb --args ...
Alternatively, you can set the environment variable from within the
GDB session before running the test:
.. code-block:: gdb-prompt
(gdb) set environment RunCMake_TEST_FILTER Metadata
(gdb) run
IDE Integration
---------------
You can also debug CMake tests directly from your IDE.
CLion
=====
If you have configured GDB to auto-load local ``.gdbinit`` files as described
above, CLion will automatically pick up the necessary settings.
A simple way to debug a test is to modify its ``CTest`` run configuration:
#. **Select the Test**: In the "Run/Debug Configurations" dialog, find the
``CTest`` entry for your test (e.g., ``RunCMake.InstallPackageInfo``).
#. **Add CTest Arguments**: In the "CTest arguments" field, add
``--extra-verbose``. This is helpful for debugging because it prints the
exact command ``CTest`` uses to run the test.
#. **Set Working Directory**: Ensure the "Working Directory" field is set to
``$CMakeCurrentLocalGenerationDir$``.
You can now set breakpoints in your code and debug this configuration.
Visual Studio Code
==================
Create a ``launch.json`` file in the ``.vscode`` directory of your
CMake **source folder** with the following configuration. This configuration
hardcodes the necessary GDB settings, so it does not depend on an external
``.gdbinit`` file.
.. code-block:: json
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug CMake Test",
"type": "cppdbg",
"request": "launch",
"program": "${workspaceFolder}/build/bin/cmake",
"args": [
"-DCMAKE_MODULE_PATH=${workspaceFolder}/Tests/RunCMake",
"-DRunCMake_GENERATOR=Ninja",
"-DRunCMake_SOURCE_DIR=${workspaceFolder}/Tests/RunCMake/InstallPackageInfo",
"-DRunCMake_BINARY_DIR=${workspaceFolder}/build/Tests/RunCMake/InstallPackageInfo",
"-P",
"${workspaceFolder}/Tests/RunCMake/RunCMakeTest.cmake"
],
"stopAtEntry": false,
"cwd": "${workspaceFolder}/build",
"environment": [],
"MIMode": "gdb",
"setupCommands": [
{
"description": "Enable pretty-printing for gdb",
"text": "-enable-pretty-printing",
"ignoreFailures": true
},
{
"description": "Follow child processes",
"text": "set follow-fork-mode child",
"ignoreFailures": true
},
{
"description": "Don't stop the parent process",
"text": "set non-stop on",
"ignoreFailures": true
}
]
}
]
}
.. note::
Remember to change the test name (``InstallPackageInfo``) in the ``"args"`` section to the specific test you want to debug.
