Debugging CMake

What compiler commands actually are executed

When cmake assembles the compiler commands, the final result can be written to a file “compile_commands.json” in the build folder by setting


either in CMakeLists.txt:


or via the command line:


This makes it easy to test the compilation of an individual file and quickly fiddle around with the options (e.g. adding or removing an option).

Where the compiler options come from

However, it’s often really hard to judge from where a specific compiler flag comes from, e.g. an include directory, as it can be set directly (e.g. target_include_directories) or indirectly from a dependency target (e.g. from target__link_libraries).

In that case on can use the following snippet to have CMake print with the following snippet in CMakeLists.txt:


which I found here.

Where dependencies come from

Dependency management in huge projects is hard. Want to reuse a component and extract it from a huge workspace? Removing parts of a project (wrappers, GUI, backends) and want to know which dependencies you now can throw out?

Try the –graphviz option of cmake:

cmake ..

This will generate a file that contains all dependencies in the project. The official documentation of this feature can be found at

To view this use dot (if you don’t have it: sudo apt install graphviz) to convert the graph file to some viewable document, e.g. to an pdf:

dot -Tpdf -o dependency-graph.pdf

Replace -Tpdf (and the filename extension) with -Tpng to get an image instead.

A neat “trick” to make the hierarchy more readable is to set rankdir="LR"; with the -G option, which changes the layout of the hierarchy to left-to-right:

dot -Grankdir="LR" -Tpdf -o dependency-tree.pdf

Tracing CMake

This one comes from the fantastic online book An Introduction to Modern CMake, specifically its chapter on debugging. Adding –trace-source=your-cmake-file will log every line that is run to the screen. Example:

cmake .. –trace-source=CMakeLists.txt

Adding --trace-expand will expand the variables to their values.