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 “配置”步骤的事件，并且，如果配置步骤正常完成，则以 ... 文档分隔符行结束

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

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

每个文档根映射的键是

events

一个 YAML 块序列，其中包含与一个 CMake “配置”步骤期间记录的事件相对应的节点。每个事件都是一个 YAML 节点，其中包含下面文档中记录的事件类型之一。

日志版本控制

每个事件类型都是独立版本控制的。事件日志条目提供的一组键特定于其主版本。当记录事件时，始终将运行的 CMake 版本已知的最新版本的事件类型写入日志。

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

  • 未来版本的 CMake 可能会引入新的事件类型或版本。

  • 如果使用不同版本的 CMake 重新配置现有构建树，则日志可能包含相同事件类型的不同版本。

  • 如果 cmake-file-api(7) 查询请求一个或多个 configureLog 对象版本，则日志可能包含同一事件的多个条目，每个条目都具有不同版本的事件类型。

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

文本块编码

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

  • \\ 编码反斜杠。

  • \xXX 使用两个十六进制数字 XX 编码一个字节。

事件类型

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

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

所有事件通用的键是

kind

一个字符串，用于标识事件类型和主版本。

backtrace

一个 YAML 块序列，报告事件发生的 CMake 源位置的调用堆栈，从最近到最远。每个节点都是一个字符串，指定一个位置，格式为 <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

一个可选键，当测试项目成功构建时存在。它的值是一个整数，指定退出代码；或者是一个字符串，包含尝试运行测试可执行文件时的错误消息。