Enable Debug Mode When Generating Build Files using CMake

When configuring a project with CMake, the output normally provides useful information about compiler checks and build setup. However, sometimes you may need to investigate what CMake is doing internally - for example, when diagnosing unexpected behavior or configuration problems. This tutorial demonstrates how to enable debug mode when generating build files using CMake.

We have a simple CMakeLists.txt file:

cmake_minimum_required(VERSION 3.27)
project(myapp)

set(CMAKE_CXX_STANDARD 17)

add_executable(${PROJECT_NAME} main.cpp)

By default, when generating the build files using CMake, you'll see output similar to this:

-- The C compiler identification is GNU 13.3.0
-- The CXX compiler identification is GNU 13.3.0
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: /usr/bin/cc - skipped
-- Detecting C compile features
-- Detecting C compile features - done
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++ - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done (0.1s)
-- Generating done (0.0s)
-- Build files have been written to: /home/ubuntu/myproject/build

If you want to see more detailed information about what happens during configuration, you can enable debug mode using --debug-output option:

cmake -S . -B build --debug-output

This activates a debug mode that not only displays regular messages but also shows the call stack and internal module invocations that CMake processes while generating the build system.

Example output with debug mode enabled (truncated output):

Running with debug output on.
-- The C compiler identification is GNU 13.3.0
   Called from: [3]     /home/ubuntu/myproject/CMakeLists.txt
                [2]     /usr/share/cmake-4.1/Modules/CMakeDetermineCCompiler.cmake
                [1]     /usr/share/cmake-4.1/Modules/CMakeDetermineCompilerId.cmake
-- The CXX compiler identification is GNU 13.3.0
   Called from: [3]     /home/ubuntu/myproject/CMakeLists.txt
                [2]     /usr/share/cmake-4.1/Modules/CMakeDetermineCXXCompiler.cmake
                [1]     /usr/share/cmake-4.1/Modules/CMakeDetermineCompilerId.cmake
-- Detecting C compiler ABI info
   Called from: [3]     /home/ubuntu/myproject/CMakeLists.txt
                [2]     /usr/share/cmake-4.1/Modules/CMakeTestCCompiler.cmake
                [1]     /usr/share/cmake-4.1/Modules/CMakeDetermineCompilerABI.cmake
...
-- Configuring done (0.1s)
   Called from: [1]     /home/ubuntu/myproject/CMakeLists.txt
-- Generating /home/ubuntu/myproject/build
   Called from: [1]     /home/ubuntu/myproject/CMakeLists.txt
-- Generating done (0.0s)
-- Build files have been written to: /home/ubuntu/myproject/build

With --debug-output, CMake reveals where each command originates and which internal modules are being executed. This mode is particularly useful for debugging complex configurations, investigating unexpected configuration results, or understanding module dependencies.