Debug

Operations for helping with debug, inspired by CMakePrintHelpers module. It requires CMake 4.0.1 or newer.

Synopsis

debug(DUMP_TARGETS <root-dir>)
debug(DUMP_VARIABLES [<INCLUDE_REGEX|EXCLUDE_REGEX> <regular-expression>])
debug(DUMP_PROPERTIES [])
debug(DUMP_TARGET_PROPERTIES <target-name>)

Usage

debug(DUMP_TARGETS <root-dir>)

Print all buildsystem and imported targets defined in the given directory <root-dir> and its subdirectories. The output displays each target prefixed by its relative directory path from CMAKE_SOURCE_DIR.

Example usage:

debug(DUMP_TARGETS "${CMAKE_SOURCE_DIR}")
# Output:
#   --
#    Targets in the project:
#      [][Buildsystem] Experimental
#      [][Buildsystem] Nightly
#   ...
#      [tests/data][Buildsystem] static_mock_lib
#      [tests/data][Buildsystem] shared_mock_lib
#      [doc][Buildsystem] doc
#      [src][Imported   ] Qt6::Platform
debug(DUMP_VARIABLES [<INCLUDE_REGEX|EXCLUDE_REGEX> <regular-expression>])

Print the list of all currently defined CMake variables and their values, useful for debugging and inspecting project scope variables. The output is sorted alphabetically and contains no duplicates.

If INCLUDE_REGEX is provided, only variables whose names match the given regular expression are printed. If EXCLUDE_REGEX is provided, variables whose names match the given expression are omitted from the output.

Example usage:

debug(DUMP_VARIABLES)
# Output:
#   --
#    Variables of CMake:
#      BUILD_SHARED_LIBS = "ON"
#      CMAKE_CURRENT_SOURCE_DIR = "/home/user/project/src"
#      CMAKE_VERSION = "3.28.3"
#      PROJECT_NAME = "MyProject"
#   ...

debug(DUMP_VARIABLES INCLUDE_REGEX "^PROJECT_")
# Output:
#   --
#    Variables of CMake:
#   ...
#      PROJECT_IS_TOP_LEVEL = "ON"
#      PROJECT_NAME = "MyProject"
#   ...

debug(DUMP_VARIABLES EXCLUDE_REGEX "^CMAKE_")
# Output:
#   --
#    Variables of CMake:
#      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:
#   --
#    Properties of CMake:
#      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:
#   --
#    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"
#      ...

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.

  • Watch a CMake variable for change:

    variable_watch(CMAKE_CXX_STANDARD)

    Check the documentation for more informations.

  • Debugging facility to print the origin of the contents of properties which may be determined by dependencies:

    set(CMAKE_DEBUG_TARGET_PROPERTIES
  INCLUDE_DIRECTORIES
  COMPILE_DEFINITIONS
  POSITION_INDEPENDENT_CODE
  CONTAINER_SIZE_REQUIRED
  LIB_VERSION
)

    Check the documentation for more informations.