CMAKE-CONFIGURE-LOG(7)

🎀 NAME 🎀

okay so bestie, welcome to the cmake-configure-log(7) manual — aka the CMake Configure Log 💖

✨ Added in version 3.26. ✨

🌸 INTRODUCTION 🌸

CMake writes a running log, known as the configure log, of certain events that occur during the Configure step. The configure log does not contain a log of all output, errors, or messages printed while configuring a project. No cap. It is a log of detailed information about specific events, such as toolchain inspection by try_compile(), meant for use in debugging the configuration of a build tree. It’s giving “receipts for your configure step” 💅

For human use, this version of CMake writes the configure log to the file:

${CMAKE_BINARY_DIR}/CMakeFiles/CMakeConfigureLog.yaml

However, the location and name of the log file may change in future versions of CMake. Tools that read the configure log should get its location using a configureLog query to the cmake-file-api(7). See the Log Versioning section below for details 🫶

🧚 LOG STRUCTURE 🧚

The configure log is designed to be both machine- and human-readable. iconic, honestly ⭐

The log file is a YAML document stream containing zero or more YAML documents separated by document markers. Each document begins with a --- document marker line, contains a single YAML mapping that logs events from one CMake “configure” step, and, if the configure step finished normally, ends with a ... document marker line:

---
events:
  -
    kind: "try_compile-v1"
    # (other fields omitted)
  -
    kind: "try_compile-v1"
    # (other fields omitted)
...

A new document is appended to the log every time CMake configures the build tree and logs new events. lowkey a diary for your build tree 📓

The keys of each document root mapping are:

• events — a YAML block sequence of nodes corresponding to events logged during one CMake “configure” step. Each event is a YAML node containing one of the Event Kinds documented below. periodt. 🌈

🦋 Log Versioning 🦋

Each of the Event Kinds is versioned independently. The set of keys an event’s log entry provides is specific to its major version. When an event is logged, the latest version of its event kind that is known to the running version of CMake is always written to the log. no mix-ups, bestie 💅

Tools reading the configure log must ignore event kinds and versions they do not understand:

• A future version of CMake may introduce a new event kind or version.
• If an existing build tree is re-configured with a different version of CMake, the log may contain different versions of the same event kind.
• If cmake-file-api(7) queries request one or more configureLog object versions, the log may contain multiple entries for the same event, each with a different version of its event kind.

IDEs should write a cmake-file-api(7) query requesting a specific configureLog object version, before running CMake, and then read the configure log only as described by the file-api reply. iykyk 🫶

🍓 Text Block Encoding 🍓

In order to make the log human-readable, text blocks are always represented using YAML literal block scalars (|). Since literal block scalars do not support escaping, backslashes and non-printable characters are encoded at the application layer:

• \\ encodes a backslash.
• \xXX encodes a byte using two hexadecimal digits, XX.

👑 EVENT KINDS 👑

Every event kind is represented by a YAML mapping of the form:

kind: "<kind>-v<major>"
backtrace:
  - "<file>:<line> (<function>)"
checks:
  - "Checking for something"
#...event-specific keys...

The keys common to all events are:

• kind — a string identifying the event kind and major version.
• backtrace — a YAML block sequence reporting the call stack of CMake source locations at which the event occurred, from most-recent to least-recent. Each node is a string specifying one location formatted as <file>:<line> (<function>).
• checks — an optional key that is present when the event occurred with at least one pending message(CHECK_START). Its value is a YAML block sequence reporting the stack of pending checks, from most-recent to least-recent. Each node is a string containing a pending check message.

Additional mapping keys are specific to each (versioned) event kind, described below. stay with me bestie, we’re going kind by kind 💖

✨ Event Kind message ✨

The message(CONFIGURE_LOG) command logs message events.

There is only one message event major version, version 1.

💌 message-v1 Event 💌

A message-v1 event is a YAML mapping:

kind: "message-v1"
backtrace:
  - "CMakeLists.txt:123 (message)"
checks:
  - "Checking for something"
message: |
  # ...

The keys specific to message-v1 mappings are:

• message — a YAML literal block scalar containing the message text, represented using our Text Block Encoding.

✨ Event Kind try_compile ✨

The try_compile() command logs try_compile events.

There is only one try_compile event major version, version 1.

💌 try_compile-v1 Event 💌

A try_compile-v1 event is a YAML mapping:

kind: "try_compile-v1"
backtrace:
  - "CMakeLists.txt:123 (try_compile)"
checks:
  - "Checking for something"
description: "Explicit LOG_DESCRIPTION"
directories:
  source: "/path/to/.../TryCompile-01234"
  binary: "/path/to/.../TryCompile-01234"
cmakeVariables:
  SOME_VARIABLE: "Some Value"
buildResult:
  variable: "COMPILE_RESULT"
  cached: true
  stdout: |
    # ...
  exitCode: 0

The keys specific to try_compile-v1 mappings are:

• description — an optional key that is present when the LOG_DESCRIPTION <text> option was used. Its value is a string containing the description <text>.
• directories — a mapping describing the directories associated with the compilation attempt. It has the following keys:
  • source — string specifying the source directory of the try_compile() project.
  • binary — string specifying the binary directory of the try_compile() project. For non-project invocations, this is often the same as the source directory.
• cmakeVariables — an optional key that is present when CMake propagates variables into the test project, either automatically or due to the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable. Its value is a mapping from variable names to their values.
• buildResult — a mapping describing the result of compiling the test code. It has the following keys:
  • variable — a string specifying the name of the CMake variable storing the result of trying to build the test project.
  • cached — a boolean indicating whether the above result variable is stored in the CMake cache.
  • stdout — a YAML literal block scalar containing the output from building the test project, represented using our Text Block Encoding. This contains build output from both stdout and stderr.
  • exitCode — an integer specifying the build tool exit code from trying to build the test project.

✨ Event Kind try_run ✨

The try_run() command logs try_run events.

There is only one try_run event major version, version 1.

💌 try_run-v1 Event 💌

A try_run-v1 event is a YAML mapping:

kind: "try_run-v1"
backtrace:
  - "CMakeLists.txt:456 (try_run)"
checks:
  - "Checking for something"
description: "Explicit LOG_DESCRIPTION"
directories:
  source: "/path/to/.../TryCompile-56789"
  binary: "/path/to/.../TryCompile-56789"
buildResult:
  variable: "COMPILE_RESULT"
  cached: true
  stdout: |
    # ...
  exitCode: 0
runResult:
  variable: "RUN_RESULT"
  cached: true
  stdout: |
    # ...
  stderr: |
    # ...
  exitCode: 0

The keys specific to try_run-v1 mappings include those documented by the try_compile-v1 event, plus:

• runResult — a mapping describing the result of running the test code. It has the following keys:
  • variable — a string specifying the name of the CMake variable storing the result of trying to run the test executable.
  • cached — a boolean indicating whether the above result variable is stored in the CMake cache.
  • stdout — an optional key that is present when the test project built successfully. Its value is a YAML literal block scalar containing output from running the test executable, represented using our Text Block Encoding.

If RUN_OUTPUT_VARIABLE was used, stdout and stderr are captured together, so this will contain both. Otherwise, this will contain only the stdout output.

• stderr — an optional key that is present when the test project built successfully and the RUN_OUTPUT_VARIABLE option was not used. Its value is a YAML literal block scalar containing output from running the test executable, represented using our Text Block Encoding.

If RUN_OUTPUT_VARIABLE was used, stdout and stderr are captured together in the stdout key, and this key will not be present. Otherwise, this will contain the stderr output.

• exitCode — an optional key that is present when the test project built successfully. Its value is an integer specifying the exit code, or a string containing an error message, from trying to run the test executable.

✨ Event Kind find ✨

The find_file(), find_path(), find_library(), and find_program() commands log find events.

There is only one find event major version, version 1.

💌 find-v1 Event 💌

Added in version 4.1.

A find-v1 event is a YAML mapping:

          kind: "find-v1"
          backtrace:
            - "CMakeLists.txt:456 (find_program)"
          mode: "program"
          variable: "PROGRAM_PATH"
          description: "Docstring for variable"
          settings:
            SearchFramework: "NEVER"
            SearchAppBundle: "NEVER"
            CMAKE_FIND_USE_CMAKE_PATH: true
            CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH: true
            CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH: true
            CMAKE_FIND_USE_CMAKE_SYSTEM_PATH: true
            CMAKE_FIND_USE_INSTALL_PREFIX: true
          names:
            - "name1"
            - "name2"
          candidate_directories:
            - "/path/to/search"
            - "/other/path/to/search"
            - "/path/to/found"
            - "/further/path/to/search"
          searched_directories:
            - "/path/to/search"
            - "/other/path/to/search"
          found: "/path/to/found/program"

okay so the keys that are specifically a find-v1 thing (like, the ones that only show up here) are these bestie:

• mode — a string that tells you which search the command actually ran. It's one of file, path, program, or library. pick your fighter 💅
• variable — the variable where the search dumped its result.
• description — the docstring of that variable. cute little lore drop 📝
• settings — the search settings that were live for this search. and inside it:
  • SearchFramework — a string saying how framework search goes down. one of FIRST, LAST, ONLY, or NEVER. see CMAKE_FIND_FRAMEWORK. 🍎
  • SearchAppBundle — a string saying how application-bundle search goes down. one of FIRST, LAST, ONLY, or NEVER. see CMAKE_FIND_APPBUNDLE. 🎀
  • CMAKE_FIND_USE_CMAKE_PATH — a boolean, is it using CMake-specific cache variables while searching or not. see CMAKE_FIND_USE_CMAKE_PATH.
  • CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH — a boolean, is it using CMake-specific environment variables while searching or not. see CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.
  • CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH — a boolean, is it using platform-specific environment variables while searching or not. see CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.
  • CMAKE_FIND_USE_CMAKE_SYSTEM_PATH — a boolean, is it using platform-specific CMake variables while searching or not. see CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.
  • CMAKE_FIND_USE_INSTALL_PREFIX — a boolean, is it using the install prefix while searching or not. see CMAKE_FIND_USE_INSTALL_PREFIX.
• names — the names it was looking for. the whole point of the quest tbh 🔍
• candidate_directories — candidate directories, in order, that it looked in during the search.
• searched_directories — directories, in order, that were actually looked at during the search process.
• found — either a string with the found value, or false if it simply was not found. it's giving "got it or didn't" energy 💀
• search_context — a mapping of variable names to the search paths those variables specified. it's either a string or an array of strings depending on the variable, no cap. environment variables get wrapped with ENV{ and }, otherwise it's CMake variables being used. and only variables that actually have some paths specified are included, so no empty boring entries. ✨
  • package_stack — an array of objects with paths that come from the stack of paths made available by find_package() calls.
    • package_paths — the paths made available by find_package() commands in the call stack.

---

🌸 Event Kind find_package 🌸

Added in version 4.1. 🆕

The find_package() command logs find_package events. literally its whole job.

There is only one find_package event major version, version 1. one and done, periodt.

🦋 find_package-v1 Event 🦋

A find_package-v1 event is a YAML mapping:

kind: "find_package-v1"
backtrace:
  - "CMakeLists.txt:456 (find_program)"
name: "PackageName"
components:
  -
    name: "Component"
    required: true
    found: true
configs:
  -
    filename: PackageNameConfig.cmake
    kind: "cmake"
  -
    filename: packagename-config.cmake
    kind: "cmake"
version_request:
  version: "1.0"
  version_complete: "1.0...1.5"
  min: "INCLUDE"
  max: "INCLUDE"
  exact: false
settings:
  required: "optional"
  quiet: false
  global: false
  policy_scope: true
  bypass_provider: false
  hints:
    - "/hint/path"
  names:
    - "name1"
    - "name2"
  search_paths:
    - "/search/path"
  path_suffixes:
    - ""
    - "suffix"
  registry_view: "HOST"
  paths:
    CMAKE_FIND_USE_CMAKE_PATH: true
    CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH: true
    CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH: true
    CMAKE_FIND_USE_CMAKE_SYSTEM_PATH: true
    CMAKE_FIND_USE_INSTALL_PREFIX: true
    CMAKE_FIND_USE_PACKAGE_ROOT_PATH: true
    CMAKE_FIND_USE_CMAKE_PACKAGE_REGISTRY: true
    CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY: true
    CMAKE_FIND_ROOT_PATH_MODE: "BOTH"
  candidates:
    -
      path: "/path/to/config/PackageName/PackageNameConfig.cmake"
      mode: "config"
      reason: "insufficient_version"
    -
      path: "/path/to/config/PackageName/packagename-config.cmake"
      mode: "config"
      reason: "no_exist"
  found:
    path: "/path/to/config/PackageName-2.5/PackageNameConfig.cmake"
    mode: "config"
    version: "2.5"

The keys specific to find_package-v1 mappings are:

• name — the name of the requested package. the main character of this whole event fr 👑
• components — if present, an array of objects with these fields:
  • name — the name of the component.
  • required — a boolean, is this component required or optional.
  • found — a boolean, was this component found or not.
• configs — if present, an array of objects telling you which configuration files it searches for.
  • filename — the filename of the configuration file.
  • kind — the kind of file. either cmake or cps.
• version_request — an object showing the version constraints on the search.
  • version — the minimum version required.
  • version_complete — the version range that the user handed over.
  • min — whether to INCLUDE or EXCLUDE the lower bound of the version range.
  • max — whether to INCLUDE or EXCLUDE the upper bound of the version range.
  • exact — a boolean, was an EXACT version match requested. no wiggle room bestie 🎯
• settings — the search settings that were active for the search.
  • required — the requirement request of the search. one of optional, optional_explicit, required_explicit, required_from_package_variable, or required_from_find_variable. so many flavours 😭
  • quiet — a boolean, is the search QUIET or not.
  • global — a boolean, was the GLOBAL keyword provided or not.
  • policy_scope — a boolean, was the NO_POLICY_SCOPE keyword provided or not.
  • bypass_provider — a boolean, was the BYPASS_PROVIDER keyword provided or not.
  • hints — an array of paths that were provided as HINTS.
  • names — an array of package names to use when searching, provided by NAMES.
  • search_paths — an array of paths to search, provided by PATHS.
  • path_suffixes — an array of suffixes to use when searching, provided by PATH_SUFFIXES.
  • registry_view — the REGISTRY_VIEW that was requested for the search.
  • paths — the path settings that were active for the search:
    • CMAKE_FIND_USE_CMAKE_PATH — a boolean, is it using CMake-specific cache variables while searching or not. see CMAKE_FIND_USE_CMAKE_PATH.
    • CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH — a boolean, is it using CMake-specific environment variables while searching or not. see CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.
    • CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH — a boolean, is it using platform-specific environment variables while searching or not. see CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.
    • CMAKE_FIND_USE_CMAKE_SYSTEM_PATH — a boolean, is it using platform-specific CMake variables while searching or not. see CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.
    • CMAKE_FIND_USE_INSTALL_PREFIX — a boolean, is it using the install prefix while searching or not. see CMAKE_FIND_USE_INSTALL_PREFIX.
    • CMAKE_FIND_USE_CMAKE_PACKAGE_REGISTRY — a boolean, should it search the CMake package registry for the package or not. see CMAKE_FIND_USE_PACKAGE_REGISTRY.

CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY

okay so this one is a boolean telling you whether or not to search the system CMake package registry for the package. See CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY <# variable:CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY>.

CMAKE_FIND_ROOT_PATH_MODE

This is a string serving the root path mode currently in effect, as selected by the CMAKE_FIND_ROOT_PATH_BOTH, ONLY_CMAKE_FIND_ROOT_PATH, and NO_CMAKE_FIND_ROOT_PATH arguments. slay ✨

candidates

An array of rejected candidate paths. bestie, each element contains these keys:

• path — the path to the considered file. In the case of a dependency provider, the value is in the form of dependency_provider::<COMMAND_NAME>.
• mode — the mode which found the file. One of module, cps, cmake, or provider.
• reason — the reason the path was rejected. One of insufficient_version, no_exist, ignored, no_config_file, or not_found.
• message — if present, a string describing why the package is considered as not found.

found

If the package has been found, this is information on the found file. If it is not found, this is null. keys available:

• path — the path to the module or configuration that found the package. In the case of a dependency provider, the value is in the form of dependency_provider::<COMMAND_NAME>.
• mode — the mode that considered the path. One of module, cps, cmake, or provider.
• version — the reported version of the package.

search_context

A mapping of variable names to search paths specified by them (either a string or an array of strings depending on the variable). Environment variables are wrapped with ENV{ and }, otherwise CMake variables are used. Only variables with any paths specified are used. iykyk 🦋

• package_stack — an array of objects with paths which come from the stack of paths made available by find_package() <# command:find_package> calls.
  • package_paths — the paths made available by find_package() <# command:find_package> commands in the call stack.

---

Copyright

2000-2026 Kitware, Inc. and Contributors

and that's the whole vibe for this page — source footer energy is version 4.4.5, dated Oct 28, 2026. bye bestie, periodt 💅✨🫶