cmake-configure-log(7)¶
在 3.26 版本中添加。
介绍¶
CMake 将某些在配置步骤中发生的事件写入运行日志，称为配置日志。配置日志不包含配置项目时打印的所有输出、错误或消息的日志。它是一些特定事件（比如 try_compile() 工具链检查）的详细信息日志，用于调试构建树的配置。
对于人工使用，此版本的 CMake 会将配置日志写入文件
${CMAKE_BINARY_DIR}/CMakeFiles/CMakeConfigureLog.yaml
然而，日志文件的路径和名称可能会在将来的 CMake 版本中更改。读取配置日志的工具应使用对 cmake-file-api(7) 的 configureLog 查询来获取其路径。有关详细信息，请参见下面的 日志版本 部分。
日志结构¶
配置日志旨在同时适合机器和人工阅读。
日志文件是一个 YAML 文档流，其中包含零个或多个 YAML 文档，通过文档标记分隔。每个文档都以 --- 文档标记行开头，包含一个单一的 YAML 映射来记录一个 CMake “configure” 步骤的事件，如果配置步骤正常完成，则以 ... 文档标记行结尾
---
events:
-
kind: "try_compile-v1"
# (other fields omitted)
-
kind: "try_compile-v1"
# (other fields omitted)
...
每次 CMake 配置构建树并记录新事件时，就会将新的文档追加到日志中。
每个文档根映射的键是
事件一个 YAML 块序列节点，对应于一个 CMake “configure” 步骤中记录的事件。每个事件是一个 YAML 节点，包含一个 事件类型（见下文）。
日志版本¶
每个 事件类型 都独立进行版本控制。一个事件日志项提供的键集取决于其主版本。记录事件时，总是将正在运行的 CMake 版本已知的该事件类型的最新版本写入日志。
读取配置日志的工具必须忽略它们不理解的事件类型和版本
未来版本的 CMake 可能会引入新的事件类型或版本。
如果现有的构建树被不同版本的 CMake 重新配置，则日志可能包含相同事件类型的不同版本。
如果
cmake-file-api(7)查询请求一个或多个 configureLog 对象版本，日志可能包含同一事件的多条条目，每个事件具有不同版本事件类型。
IDE 应该在运行 CMake 之前编写 cmake-file-api(7) 查询请求特定的 configureLog 对象版本，然后仅根据文件 API 回复中所述读取配置日志。
文本块编码¶
为了使日志可被人阅读，始终使用 YAML 字面量块标量表示文本块 (|)。由于字面量块标量不支持转义，因此反斜杠和不可打印的字符在应用程序层进行编码
\\编码一个反斜杠。\xXX使用两个十六进制数字XX编码一个字节。
事件类型¶
每种事件类型都由下述形式的 YAML 映射表示
kind: "<kind>-v<major>"
backtrace:
- "<file>:<line> (<function>)"
checks:
- "Checking for something"
#...event-specific keys...
所有事件通用的键为
kind标识事件类型和主要版本的字符串。
backtrace报告事件发生的 CMake 源代码位置的调用堆栈的 YAML 块序列，从最近到最远。每个节点是将一个位置格式化为
<file>:<line> (<function>)的字符串。checks事件至少发生一次待处理
message(CHECK_START)时，才会显示此可选键。其值为报告待处理检查堆栈的 YAML 块序列，从最近到最远。每个节点包含一个待处理检查消息的字符串。
其他映射键特定于每个（版本化的）事件类型，如下所述。
事件类型 message¶
message(CONFIGURE_LOG) 命令记录 message 事件。
只有一个 message 事件主版本，版本 1。
message-v1 事件¶
message-v1 事件是 YAML 映射
kind: "message-v1"
backtrace:
- "CMakeLists.txt:123 (message)"
checks:
- "Checking for something"
message: |
# ...
对于 message-v1 映射，其特定键为
message包含消息文本的 YAML 字面量块标量，使用我们的 文本块编码 表示。
事件类型 try_compile¶
记录 try_compile() 事件的 try_compile() 命令。
仅有一个 try_compile 事件主要版本，即版本 1。
try_compile-v1 事件¶
try_compile-v1 事件是 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
特定于 try_compile-v1 映射的键为
description在使用
LOG_DESCRIPTION <text>选项时出现的可选键。其值为包含说明<text>的字符串。directories描述与编译尝试关联的目录的映射。它具有以下键
source指定
try_compile()项目的源目录的字符串。binary指定
try_compile()项目的二进制目录的字符串。对于非项目调用，这通常与源目录相同。
cmakeVariables在 CMake 将变量传播到测试项目（无论是自动执行的，还是由于
CMAKE_TRY_COMPILE_PLATFORM_VARIABLES变量）时出现的可选键。其值为从变量名到变量值的映射。buildResult描述编译测试代码结果的映射。它具有以下键
variable指定存储尝试构建测试项目的 CMake 变量名称的字符串。
cached指示上述结果
variable是否存储在 CMake 缓存中的布尔值。stdout包含通过构建测试项目产生的输出的 YAML 文字块标量，使用我们的 文本块编码 来表示。这包含 stdout 和 stderr 中的构建输出。
exitCode尝试构建测试项目的构建工具退出代码的整型。
事件种类 try_run¶
记录 try_run 事件的 try_run() 命令。
仅有一个 try_run 事件主要版本，即版本 1。
try_run-v1 事件¶
try_run-v1 事件是 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
特定于 try_run-v1 的键映射包括 try_compile-v1 事件 中记录的那些键，外加
runResult描述运行测试代码的结果的映射。它具有以下键
variable一个指定存储尝试运行测试可执行文件的 CMake 变量名称的字符串。
cached指示上述结果
variable是否存储在 CMake 缓存中的布尔值。stdout一个在测试项目成功构建时存在的可选键。其值为 YAML 标量文本块，包含使用我们的 文本块编码 表示的用于运行测试可执行文件的输出。
如果使用了
RUN_OUTPUT_VARIABLE，则会同时捕获 stdout 和 stderr，因此这将同时包含两者。否则，这将仅包含 stdout 输出。stderr一个在测试项目成功构建并且未使用
RUN_OUTPUT_VARIABLE选项时存在的可选键。其值为 YAML 标量文本块，包含使用我们的 文本块编码 表示的用于运行测试可执行文件的输出。如果使用了
RUN_OUTPUT_VARIABLE，则 stdout 和 stderr 将同时捕获到stdout键中，此键将不存在。否则，这将包含 stderr 输出。exitCode一个在测试项目成功构建时存在的可选键。其值为指定退出代码的整数，或尝试运行测试可执行文件时产生的错误消息的字符串。