How can I debug CMakeLists.txt files?

Question

How can I debug CMakeLists.txt files (at least doing things like listing of variables) other than just using the message() command?

Answer 1

If you're using an IDE,

• CLion announced their CMake debugger on October 25, 2022

  • more docs at https://www.jetbrains.com/help/clion/cmake-debug.html.

• Visual Studio announced their CMake debugger on February 22nd, 2023

• Qt Creator will likely have a CMake debugger in the future

• Visual Studio's CMake debugger is available in VS Code (announced on Aug 9th, 2023). Docs for it are here.

Related to that, CMake 3.27 exposes the --debugger flag to enable interactive debugging using the Debug Adapter Protocol. See also the --cmake-debugger-pipe flag and the --debugger-dap-log flag.

Otherwise,

Pre-CMake v3.26, you can (as suggested by CMake's diagnostic messages) look at the CMakeFiles/CMakeOutput.log and CMakeFiles/CMakeError.log files in the generated buildsystem's binary/build directory.

Starting with CMake v3.26, the CMakeFiles/CMakeOutput.log and CMakeFiles/CMakeError.log files will no longer be supported / created. From the release notes:

The CMakeFiles/CMakeOutput.log and CMakeFiles/CMakeError.log files are no longer populated by CMake's built-in modules. cmake(1) no longer suggests looking at them after a CMake Error occurs. Information previously logged to those files is instead logged to the cmake-configure-log(7).

Other CMake debug-related facilities you may find useful include to following:

• To put CMake in a trace mode where it prints all calls made and from where, use the --trace flag and/or related flags like --trace-expand, --trace-format, --trace-source and --trace-redirect.

• To make CMake print commands in execute_process calls, use the CMAKE_EXECUTE_PROCESS_COMMAND_ECHO variable.

• To make CMake emit developer warnings meant for CMakeLists.txt authors, use the -Wdev flag

• To make CMake emit warnings about deprecated functionality, use the -Wdeprecated flag

• To put CMake in a debugging mode where it prints things like stack traces with message(SEND_ERROR) calls, use the --debug-output flag

• To watch variables for changes, use the variable_watch command.

• To enable tracing output when evaluating a certain set of target properties, use the CMAKE_DEBUG_TARGET_PROPERTIES variable.

• To make CMake warn when uninitialized variables are used, use the --warn-uninitialized flag.

• To debug commands that find things like find_program(), find_library(), find_file(), find_path(), and find_package(), use the --debug-find flag, or for debugging at more granular scopes, the CMAKE_FIND_DEBUG_MODE variable.

• To debug try_compile/try_run failures, use the --debug-trycompile flag

• If you want to do performance profiling of CMake script execution, see the --profiling-output and --profiling-output flags.

• To make CMake print its global inter-target dependency graph, which it generates at the beginning of native build system generation, use the GLOBAL_DEPENDS_DEBUG_MODE global property.

Bonus info: If you want to profile build performance, you can look into the facilities provided by the tools in your toolchain, such as Ninja and Clang. Craig Scott has written an article on the subject here: https://crascit.com/2022/06/24/build-performance-insights/.

Answer 2

As it wasn't mentioned, I'd like to add: If you want to debug the effective invocations of execute_process(), you can pass -D CMAKE_EXECUTE_PROCESS_COMMAND_ECHO=STDOUT|STDERR, and the corresponding cmdlines are printed. Requires CMake >= 3.15. Very helpful in my case.

Answer 3

At the time of originally writing this answer, there were no interactive debugger for CMake, but it was possible to use the flags -Wdev, --debug-output and --trace for additional information and to check the log files CMakeFiles\CMakeOutput.log and CMakeFiles\CMakeError.log which mainly collect outputs of processes called by CMake (for example while checking for presence of a type or header).

Since version 3.7, CMake now officially supports a "server mode" so integration in IDEs is likely to improve in the near future. Initial support exists both in Qt Creator and Visual Studio 2017 RC

Since version 3.27, CMake also supports the Debug Adapter Protocol and several IDE vendors (for example CLion or Visual Studio) now either support or have announced support for CMake debugging. How it works exactly depends on the specific IDE.

Answer 4

Starting with version 3.27, CMake comes with a built-in debugger. Start cmake with --debugger and it will expose debugging via the Debug Adapter Protocol.

Documentation: https://cmake.org/cmake/help/latest/manual/cmake.1.html#cmdoption-cmake-debugger

Answer 5

Also, read about the env var VERBOSE: https://cmake.org/cmake/help/latest/envvar/VERBOSE.html

I used it this way:

export VERBOSE=defined
make

and got some more verbosity.

In other cases, edit CMakeLists.txt file to include the following line:

set(CMAKE_VERBOSE_MAKEFILE ON)

(Some post on this is https://bytefreaks.net/programming-2/make-building-with-cmake-verbose ).

Also, there are useful cmake options controlling debug output, see the manpage: https://cmake.org/cmake/help/latest/manual/cmake.1.html

Answer 6

I like to use variable_watch to "debug" my CMakeLists.txt files. Just set in top of my script:

variable_watch(SOME_MY_VAR)

Answer 7

You can try using the new CMake Script Debugger provided by the VisualGDB tool. It uses an open-source fork of CMake that supports stepping through CMakeLists.txt files, setting code/data breakpoints, evaluating/changing variables, etc.

There's a detailed step-by-step tutorial on the new debugger here

Answer 8

There are steveire's CMake Daemon Tools. I haven't used them myself, but they claim to offer possibilities for introspection that seem to be pretty close to a debugger.

Edit: They are now called CMake-server and are part of CMake 3.7.