Help/manual/cmake-configure-log.7.rst
.. cmake-manual-description: CMake Configure Log
cmake-configure-log(7)
.. versionadded:: 3.26
.. only:: html
.. contents::
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. It is a log of
detailed information about specific events, such as toolchain inspection
by :command:try_compile, meant for use in debugging the configuration
of a build tree.
For human use, this version of CMake writes the configure log to the file:
.. code-block:: cmake
${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 :ref:configureLog <file-api configureLog> query to
the :manual:cmake-file-api(7).
See the Log Versioning_ section below for details.
The configure log is designed to be both machine- and human-readable.
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:
.. code-block:: yaml
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.
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.
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.
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 :manual:cmake-file-api(7) queries request one or more
:ref:configureLog <file-api 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 :manual:cmake-file-api(7) query requesting a
specific :ref:configureLog <file-api configureLog> object version,
before running CMake, and then read the configure log only as described
by the file-api reply.
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... _configure-log event kinds:
Every event kind is represented by a YAML mapping of the form:
.. code-block:: yaml
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 :command: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.
.. _message configure-log event:
messageThe :command:message(CONFIGURE_LOG) command logs message events.
There is only one message event major version, version 1.
.. _message-v1 event:
message-v1 Event
^^^^^^^^^^^^^^^^^^^^
A message-v1 event is a YAML mapping:
.. code-block:: yaml
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_.
.. _try_compile configure-log event:
try_compileThe :command:try_compile command logs try_compile events.
There is only one try_compile event major version, version 1.
.. _try_compile-v1 event:
try_compile-v1 Event
^^^^^^^^^^^^^^^^^^^^^^^^
A try_compile-v1 event is a YAML mapping:
.. code-block:: yaml
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
:command:try_compile project.
binary
String specifying the binary directory of the
:command: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
:variable: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.
.. _try_run configure-log event:
try_runThe :command:try_run command logs try_run events.
There is only one try_run event major version, version 1.
.. _try_run-v1 event:
try_run-v1 Event
^^^^^^^^^^^^^^^^^^^^
A try_run-v1 event is a YAML mapping:
.. code-block:: yaml
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.
.. _find configure-log event:
findThe :command:find_file, :command:find_path, :command:find_library, and
:command:find_program commands log find events.
There is only one find event major version, version 1.
.. _find-v1 event:
find-v1 Event
^^^^^^^^^^^^^^^^^
.. versionadded:: 4.1
A find-v1 event is a YAML mapping:
.. code-block:: yaml
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"
The keys specific to find-v1 mappings are:
mode
A string describing the command using the search performed. One of file,
path, program, or library.
variable
The variable to which the search stored its result.
description
The documentation string of the variable.
settings
Search settings active for the search.
SearchFramework
A string describing how framework search is performed. One of FIRST,
LAST, ONLY, or NEVER. See :variable:CMAKE_FIND_FRAMEWORK.
SearchAppBundle
A string describing how application bundle search is performed. One of
FIRST, LAST, ONLY, or NEVER. See
:variable:CMAKE_FIND_APPBUNDLE.
CMAKE_FIND_USE_CMAKE_PATH
A boolean indicating whether or not CMake-specific cache variables are
used when searching. See :variable:CMAKE_FIND_USE_CMAKE_PATH.
CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
A boolean indicating whether or not CMake-specific environment variables
are used when searching. See
:variable:CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH.
CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH
A boolean indicating whether or not platform-specific environment
variables are used when searching. See
:variable:CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH.
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
A boolean indicating whether or not platform-specific CMake variables are
used when searching. See :variable:CMAKE_FIND_USE_CMAKE_SYSTEM_PATH.
CMAKE_FIND_USE_INSTALL_PREFIX
A boolean indicating whether or not the install prefix is used when
searching. See :variable:CMAKE_FIND_USE_INSTALL_PREFIX.
names
The names to look for the queries.
candidate_directories
Candidate directories, in order, to look in during the search.
searched_directories
Directories, in order, looked at during the search process.
found
Either a string representing the found value or false if it was not
found.
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.
package_stack
An array of objects with paths which come from the stack of paths made
available by :command:find_package calls.
``package_paths``
The paths made available by :command:`find_package` commands in the call
stack.
.. _find_package configure-log event:
find_package.. versionadded:: 4.1
The :command:find_package command logs find_package events.
There is only one find_package event major version, version 1.
.. _find_package-v1 event:
find_package-v1 Event
^^^^^^^^^^^^^^^^^^^^^^^^^
A find_package-v1 event is a YAML mapping:
.. code-block:: yaml
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.
components
If present, an array of objects containing the fields:
name
The name of the component.
required
A boolean indicating whether the component is required or optional.
found
A boolean indicating whether the component was found or not.
configs
If present, an array of objects indicating the configuration files to search
for.
filename
The filename of the configuration file.
kind
The kind of file. Either cmake or cps.
version_request
An object indicating the version constraints on the search.
version
The minimum version required.
version_complete
The user-provided version range.
min
Whether to INCLUDE or EXCLUDE the lower bound on the version
range.
max
Whether to INCLUDE or EXCLUDE the upper bound on the version
range.
exact
A boolean indicating whether an EXACT version match was requested.
settings
Search settings 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.
quiet
A boolean indicating whether the search is QUIET or not.
global
A boolean indicating whether the GLOBAL keyword has been provided or
not.
policy_scope
A boolean indicating whether the NO_POLICY_SCOPE keyword has been
provided or not.
bypass_provider
A boolean indicating whether the BYPASS_PROVIDER keyword has been
provided or not.
hints
An array of paths 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 requested for the search.
paths
Path settings active for the search.
``CMAKE_FIND_USE_CMAKE_PATH``
A boolean indicating whether or not CMake-specific cache variables are
used when searching. See :variable:`CMAKE_FIND_USE_CMAKE_PATH`.
``CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH``
A boolean indicating whether or not CMake-specific environment variables
are used when searching. See
:variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH`.
``CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH``
A boolean indicating whether or not platform-specific environment
variables are used when searching. See
:variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH`.
``CMAKE_FIND_USE_CMAKE_SYSTEM_PATH``
A boolean indicating whether or not platform-specific CMake variables are
used when searching. See :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`.
``CMAKE_FIND_USE_INSTALL_PREFIX``
A boolean indicating whether or not the install prefix is used when
searching. See :variable:`CMAKE_FIND_USE_INSTALL_PREFIX`.
``CMAKE_FIND_USE_CMAKE_PACKAGE_REGISTRY``
A boolean indicating whether or not to search the CMake package registry
for the package. See :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`.
``CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY``
A boolean indicating whether or not to search the system CMake package
registry for the package. See
:variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`.
``CMAKE_FIND_ROOT_PATH_MODE``
A string indicating the root path mode in effect as selected by the
``CMAKE_FIND_ROOT_PATH_BOTH``, ``ONLY_CMAKE_FIND_ROOT_PATH``, and
``NO_CMAKE_FIND_ROOT_PATH`` arguments.
candidates
An array of rejected candidate paths. Each element contains the following
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, 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.
package_stack
An array of objects with paths which come from the stack of paths made
available by :command:find_package calls.
``package_paths``
The paths made available by :command:`find_package` commands in the call
stack.