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?

Might be helpful, too: http://stackoverflow.com/a/38869455/2799037 — usr1234567, Jan 04 '17 at 14:24

Joe · Accepted Answer · 2023-07-20T08:25:55.443

68

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.

edited Jul 20 '23 at 08:25

answered Apr 02 '14 at 07:02

Joe

6,497
4
29
55

Which one do we use to debug `if` statements in `CmakeList.txt`? `came --debug ...` and `cmake --debug-output ...` are not printing them. In Bash, the equivalent is `bash -x `. – jww Sep 14 '16 at 16:44
@jww I'm not 100% sure what you are trying to debug, but the output of `--trace` is usually quite extensive (redirect the output to a file!) – Joe Sep 15 '16 at 05:27
I was trying to debug the script and understand why certain code blocks were not being entered. But I found the problem: `string(STRIP ...)` was broken. Also see [How to strip trailing newline in Cmake variable?](http://stackoverflow.com/q/39496043/). My apologies if you did not know what `bash -x` does. – jww Sep 15 '16 at 05:44
2

You shouldn't just mention checking the logs. You should explain how one goes about checking the logs. – Thomas Jay Rush Dec 22 '18 at 13:20
@ThomasJayRush I added information about the location and content of the log files. Anything beyond that depends on the specific issue. – Joe Jan 22 '19 at 11:19
Now there are [interactive debuggers](https://stackoverflow.com/a/75701905/5197544) – Кое Кто Jun 23 '23 at 16:03
@КоеКто I have updated my answer to reflect the additional debugger support added in CMake 3.27 – Joe Jul 20 '23 at 08:27

score 13 · Answer 2 · answered Oct 10 '18 at 19:15

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

score 10 · Answer 3 · answered Aug 27 '19 at 09:46

10

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

variable_watch(SOME_MY_VAR)

answered Aug 27 '19 at 09:46

leanid.chaika

2,143
2
27
30

usr1234567 · Answer 4 · 2017-01-04T14:23:03.420

5

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.

edited Jan 04 '17 at 14:23

answered Aug 10 '16 at 09:43

usr1234567

21,601
16
108
128

starball · Answer 5 · 2023-09-01T22:27:07.910

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)

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 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 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.

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/.

Eugene Gr. Philippov · Answer 6 · 2020-01-30T17:28:28.277

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

score 0 · Answer 7 · answered Jun 23 '23 at 20:49

0

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

answered Jun 23 '23 at 20:49

usr1234567

21,601
16
108
128

1

note: this is already covered in my answer: https://stackoverflow.com/a/75701905/11107541 – starball Jun 23 '23 at 21:27

How can I debug CMakeLists.txt files?

7 Answers7

Linked

Related