cmake 配置日志(7)¶

在 3.26 版本加入.

介绍 ¶

CMake 为配置步骤中发生的某些事件写入运行日志，称为*配置日志*。配置日志不包含配置项目时打印的所有输出、错误或消息的日志。它是有关特定事件的详细信息的日志，例如:command:try_compile 的工具链检查，用于调试构建树的配置。

对于人类使用，此版本的 CMake 将配置日志写入文件

${CMAKE_BINARY_DIR}/CMakeFiles/CMakeConfigureLog.yaml

但是，日志文件的*位置和名称可能会在未来的 CMake 版本中更改*。读取配置日志的工具应该使用 configureLog 查询到 cmake-file-api(7) 来获取它的位置。有关详细信息，请参阅下面的“日志版本控制”部分。

日志结构 ¶

配置日志被设计为机器和人类都可读。

日志文件是一个 YAML 文档流，包含零个或多个由文档标记分隔的 YAML 文档。每个文档都以“---”文档标记行开头，包含一个 YAML 映射，用于记录来自一个 CMake“配置”步骤的事件，并且如果配置步骤正常完成，则以“...”结束` 文档标记行：

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

每次 CMake 配置构建树并记录新事件时，都会将一个新文档附加到日志中。

每个文档根映射的键是：

事件: 一个 YAML 块节点序列，对应于在一个 CMake“配置”步骤中记录的事件。每个事件都是一个 YAML 节点，其中包含下面记录的“事件种类”之一。

日志版本控制 ¶

每个“事件种类”都是独立版本化的。事件日志条目提供的键集特定于其主要版本。记录事件时，运行版本的 CMake 已知的事件类型的最新版本始终写入日志。

读取配置日志的工具必须忽略它们不理解的事件种类和版本：

CMake 的未来版本可能会引入新的事件类型或版本。
如果使用不同版本的 CMake 重新配置现有构建树，则日志可能包含同一事件类型的不同版本。
如果 cmake-file-api(7) 查询请求一个或多个 configureLog 对象版本，日志可能包含同一事件的多个条目，每个条目都有不同的版本它的事件类型。

IDE 应该在运行 CMake 之前编写一个请求特定 configureLog 对象版本的 cmake-file-api(7) 查询，然后仅按照如下所述读取配置日志文件 API 回复。

文本块编码 ¶

为了使日志易于阅读，文本块始终使用 YAML 文字块标量 (|) 表示。由于文字块标量不支持转义，因此反斜杠和不可打印字符在应用层进行编码：

\\ 编码反斜杠。
\xXX 使用两个十六进制数字 XX 对一个字节进行编码。

活动种类 ¶

每个事件类型都由以下形式的 YAML 映射表示：

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

所有事件共有的键是：

善良: 标识事件类型和主要版本的字符串。
回溯: YAML 块序列报告事件发生的 CMake 源位置的调用堆栈，从最近到最近。每个节点都是一个字符串，指定一个格式为“<file>:<line> (<function>)”的位置。
检查: 一个可选键，当事件发生时至少有一个待处理的 message(CHECK_START) 出现。它的值是一个 YAML 块序列，报告待处理检查的堆栈，从最近到最近。每个节点都是一个包含待处理检查消息的字符串。

其他映射键特定于每个（版本化的）事件类型，如下所述。

事件种类``消息``¶

message(CONFIGURE_LOG) 命令记录 message 事件。

只有一个“消息”事件主要版本，版本 1。

`message-v1` 事件 ¶

message-v1 事件是一个 YAML 映射：

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

特定于“message-v1”映射的键是：

消息: 包含消息文本的 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 映射特有的键是：

描述

使用 LOG_DESCRIPTION <text> 选项时出现的可选键。它的值是一个包含描述“<text>”的字符串。

目录

描述与编译尝试关联的目录的映射。它具有以下键：

来源: 指定 try_compile() 项目源目录的字符串。
二进制: 指定 try_compile() 项目的二进制目录的字符串。对于非项目调用，这通常与源目录相同。

cmakeVariables

当 CMake 自动或由于 CMAKE_TRY_COMPILE_PLATFORM_VARIABLES 变量将变量传播到测试项目时出现的可选键。它的值是从变量名到它们的值的映射。

构建结果

描述编译测试代码结果的映射。它具有以下键：

变量: 一个字符串，指定存储尝试构建测试项目的结果的 CMake 变量的名称。
缓存: 一个布尔值，指示上述结果“变量”是否存储在 CMake 缓存中。
标准输出: 一个 YAML 文字块标量，包含构建测试项目的输出，使用我们的“文本块编码”表示。这包含来自 stdout 和 stderr 的构建输出。
退出代码: 一个整数，指定用于尝试构建测试项目的构建工具退出代码。

事件种类``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 事件记录的键，以及：

运行结果

描述运行测试代码的结果的映射。它具有以下键：

变量

一个字符串，指定存储尝试运行测试可执行文件的结果的 CMake 变量的名称。

缓存

一个布尔值，指示上述结果“变量”是否存储在 CMake 缓存中。

标准输出

成功构建测试项目时出现的可选密钥。它的值是一个 YAML 文字块标量，包含运行测试可执行文件的输出，使用我们的“文本块编码”表示。

如果使用了``RUN_OUTPUT_VARIABLE``，stdout 和stderr 会一起捕获，所以这将包含两者。否则，这将只包含 stdout 输出。

标准错误

当测试项目成功构建且未使用“RUN_OUTPUT_VARIABLE”选项时出现的可选键。它的值是一个 YAML 文字块标量，包含运行测试可执行文件的输出，使用我们的“文本块编码”表示。

如果使用了``RUN_OUTPUT_VARIABLE``，stdout 和stderr 将一起捕获在``stdout`` 键中，并且该键将不存在。否则，这将包含 stderr 输出。

退出代码

成功构建测试项目时出现的可选密钥。它的值是一个整数，指定退出代码，或一个包含错误消息的字符串，用于尝试运行测试可执行文件。