Debug

Operations for helping with debug. It requires CMake 3.20 or newer.

Synopsis

debug(DUMP_VARIABLES [EXCLUDE_REGEX <regular-expression>])
debug(DUMP_PROPERTIES [])
debug(DUMP_TARGET_PROPERTIES <target-name>)
debug(DUMP_PROJECT_VARIABLES [])

Usage

debug(DUMP_VARIABLES [EXCLUDE_REGEX <regular-expression>])

Disaply all CMake variables except those that match with the optional <regular-expression> parameter.

Display all defined CMake variables, optionally excluding those whose names match a given regular expression.

This command retrieves all variables currently defined in the CMake context and prints their names and values using message(). The output is sorted alphabetically and contains no duplicates.

If <regular-expression> is provided, any variable whose name matches the given expression is omitted from the output.

Example usage:

debug(DUMP_VARIABLES)
# output is:
#   BUILD_SHARED_LIBS=ON
#   CMAKE_CURRENT_SOURCE_DIR=/home/user/project/src
#   CMAKE_VERSION=3.28.3
#   PROJECT_NAME=MyProject
#   ...

debug(DUMP_VARIABLES
  EXCLUDE_REGEX "^CMAKE_"
)
# output is:
#   BUILD_SHARED_LIBS=ON
#   PROJECT_NAME=MyProject
#   ...
debug(DUMP_PROPERTIES [])

Display all CMake properties available in the current version of CMake.

This command executes the equivalent of cmake.--help-property-list and prints each property name using message(). The output is sorted alphabetically.

It provides a quick reference for all built-in CMake properties, including those related to targets, directories, sources, tests, cache entries, and more.

This command does not inspect actual property values but rather enumerates all recognized property names in the CMake environment.

Example usage:

debug(DUMP_PROPERTIES)
# output is:
#   ADDITIONAL_CLEAN_FILES
#   ALIAS_GLOBAL
#   ANDROID_API
#   ARCHIVE_OUTPUT_DIRECTORY
#   AUTOMOC
#   ...
debug(DUMP_TARGET_PROPERTIES <target-name>)

Display all defined CMake properties of the given target <target-name>.

This command enumerates all known target properties supported by CMake, including custom properties specific to the project. For each property set on the target, its value is printed using message().

Configuration-specific properties such as IMPORTED_LOCATION_<CONFIG> or INTERFACE_INCLUDE_DIRECTORIES_<CONFIG> (a custom property used by Dependency module) are expanded for DEBUG and RELEASE configurations. Internal properties like LOCATION and those known to trigger errors on access are excluded from the output.

Example usage:

debug(DUMP_TARGET_PROPERTIES my_library)
# output is:
#
#   -----
#   Properties for TARGET my_library:
#     my_library.TYPE = "STATIC_LIBRARY"
#     my_library.SOURCES = "src/a.cpp;src/b.cpp"
#     my_library.INTERFACE_INCLUDE_DIRECTORIES = "include"
#     ...
#   -----
#
debug(DUMP_PROJECT_VARIABLES [])

Display all global CMake variables related to the current project.

This command prints the values of all defined variables whose name starts with the current PROJECT_NAME. This relies on the naming convention that project-specific variables are prefixed with the project name followed by an underscore.

This command is useful for debugging and inspecting variables that are explicitly scoped to the project. It filters out unrelated variables defined by CMake or third-party scripts.

Example usage:

debug(DUMP_PROJECT_VARIABLES)
# output is:
#
#   -----
#   Variables for PROJECT my_project:
#     my_project_SOURCE_DIR = "/home/user/my_project/src"
#     my_project_BUILD_DIR = "/home/user/my_project/build"
#     ...
#     -----
#

Additional commands

CMake provides convenience commands, primarily intended for debugging, to print various information about the CMake environment.

  • Printing the values of properties for the specified targets, source files, directories, tests, or cache entries:

    include(CMakePrintHelpers)
cmake_print_properties(<[TARGETS <target-name>...] |
                      [SOURCES <file-path>...] |
                      [DIRECTORIES <dir-path>...] |
                      [TESTS <test-name>...] |
                      [CACHE_ENTRIES <entry-name>...]>
                      PROPERTIES <property-name>...
)

    Check the documentation for more informations.

  • Printing each variable name followed by its value:

    include(CMakePrintHelpers)
cmake_print_variables(<var>...)

    Check the documentation for more informations.

  • Printing system information and various internal CMake variables for diagnostics:

    include(CMakePrintSystemInformation)

    Check the documentation for more informations.

  • Print a dependency graph of the targets:

    set_property(GLOBAL PROPERTY GLOBAL_DEPENDS_DEBUG_MODE 1)

    Check the documentation for more informations.

  • Since generator expressions are evaluated during generation of the buildsystem, and not during processing of CMakeLists.txt files, this command allows to interpret a generator expression:

    file(GENERATE OUTPUT debug.txt CONTENT "$<...>")

    Check the documentation for more informations.