cmake-configure-log(7)¶

3.26 版新增。

简介 ¶

CMake 在配置步骤期间发生的某些事件会写入一个运行日志，称为 *配置日志*。配置日志 *不* 包含配置项目时所有输出、错误或消息的日志。它是关于特定事件的详细信息日志，例如 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) 查询，然后仅按照 file-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`¶

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 映射的键是

消息: 包含消息文本的 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() 项目二进制目录的字符串。对于非项目调用，这通常与源目录相同。

cmake变量

当 CMake 自动或由于 CMAKE_TRY_COMPILE_PLATFORM_VARIABLES 变量而将变量传播到测试项目时，存在的可选键。其值是变量名称到其值的映射。

构建结果

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

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

事件类型 `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 event 中记录的那些，以及

运行结果

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

变量

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

缓存

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

标准输出

当测试项目成功构建时存在的可选键。其值是一个 YAML 字面量块标量，包含运行测试可执行文件的输出，使用我们的文本块编码表示。

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

stderr

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

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

退出码

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

事件类型 `find`¶

find_file()、find_path()、find_library() 和 find_program() 命令记录 find 事件。

find 事件只有一个主要版本，版本 1。

`find-v1` 事件 ¶

在 4.1 版本中新增。

一个 find-v1 事件是一个 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"

特定于 find-v1 映射的键是

模式

描述使用所执行搜索的命令的字符串。可以是 file、path、program 或 library 之一。

变量

搜索结果存储到的变量。

描述

变量的文档字符串。

设置

搜索的活动搜索设置。

SearchFramework: 描述框架搜索如何执行的字符串。可以是 FIRST、LAST、ONLY 或 NEVER 之一。请参见 CMAKE_FIND_FRAMEWORK。
SearchAppBundle: 描述应用程序包搜索如何执行的字符串。可以是 FIRST、LAST、ONLY 或 NEVER 之一。请参见 CMAKE_FIND_APPBUNDLE。
CMAKE_FIND_USE_CMAKE_PATH: 一个布尔值，指示在搜索时是否使用 CMake 特定的缓存变量。请参见 CMAKE_FIND_USE_CMAKE_PATH。
CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH: 一个布尔值，指示在搜索时是否使用 CMake 特定的环境变量。请参见 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH。
CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH: 一个布尔值，指示在搜索时是否使用平台特定的环境变量。请参见 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH。
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH: 一个布尔值，指示在搜索时是否使用平台特定的 CMake 变量。请参见 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH。
CMAKE_FIND_USE_INSTALL_PREFIX: 一个布尔值，指示在搜索时是否使用安装前缀。请参见 CMAKE_FIND_USE_INSTALL_PREFIX。

名称

要查询的名称。

候选目录

搜索过程中按顺序查找的候选目录。

已搜索的目录

在搜索过程中按顺序查看的目录。

找到

一个字符串，表示找到的值，如果没有找到则为 false。

搜索上下文

变量名称到它们指定的搜索路径的映射（根据变量，可以是字符串或字符串数组）。环境变量用 ENV{ 和 } 包裹，否则使用 CMake 变量。只使用指定了任何路径的变量。

包栈

一个对象数组，其中包含由 find_package() 调用提供的路径栈。

包路径: 调用堆栈中 find_package() 命令提供的路径。

事件类型 `find_package`¶

在 4.1 版本中新增。

find_package() 命令记录 find_package 事件。

find_package 事件只有一个主要版本，版本 1。

`find_package-v1` 事件 ¶

一个 find_package-v1 事件是一个 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"

特定于 find_package-v1 映射的键是

名称

所请求包的名称。

组件

如果存在，一个包含以下字段的对象数组：

名称: 组件的名称。
必需: 一个布尔值，指示组件是必需的还是可选的。
找到: 一个布尔值，指示组件是否已找到。

配置

如果存在，一个对象数组，指示要搜索的配置文件。

文件名: 配置文件的文件名。
种类: 文件类型。可以是 cmake 或 cps。

版本请求

一个对象，指示搜索的版本约束。

版本: 所需的最低版本。
版本完整: 用户提供的版本范围。
最小值: 是否 INCLUDE 或 EXCLUDE 版本范围的下限。
最大值: 是否 INCLUDE 或 EXCLUDE 版本范围的上限。
精确: 一个布尔值，指示是否请求了 EXACT 版本匹配。

设置

搜索的活动搜索设置。

必需

搜索的请求要求。可以是 optional、optional_explicit、required_explicit、required_from_package_variable 或 required_from_find_variable 之一。

安静

一个布尔值，指示搜索是否 QUIET。

全局

一个布尔值，指示是否提供了 GLOBAL 关键字。

策略范围

一个布尔值，指示是否提供了 NO_POLICY_SCOPE 关键字。

绕过提供者

一个布尔值，指示是否提供了 BYPASS_PROVIDER 关键字。

提示

作为 HINTS 提供的路径数组。

名称

搜索时使用的包名称数组，由 NAMES 提供。

搜索路径

要搜索的路径数组，由 PATHS 提供。

路径后缀

搜索时使用的后缀数组，由 PATH_SUFFIXES 提供。

注册表视图

搜索请求的 REGISTRY_VIEW。

路径

搜索的活动路径设置。

CMAKE_FIND_USE_CMAKE_PATH: 一个布尔值，指示在搜索时是否使用 CMake 特定的缓存变量。请参见 CMAKE_FIND_USE_CMAKE_PATH。
CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH: 一个布尔值，指示在搜索时是否使用 CMake 特定的环境变量。请参见 CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH。
CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH: 一个布尔值，指示在搜索时是否使用平台特定的环境变量。请参见 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH。
CMAKE_FIND_USE_CMAKE_SYSTEM_PATH: 一个布尔值，指示在搜索时是否使用平台特定的 CMake 变量。请参见 CMAKE_FIND_USE_CMAKE_SYSTEM_PATH。
CMAKE_FIND_USE_INSTALL_PREFIX: 一个布尔值，指示在搜索时是否使用安装前缀。请参见 CMAKE_FIND_USE_INSTALL_PREFIX。
CMAKE_FIND_USE_CMAKE_PACKAGE_REGISTRY: 一个布尔值，指示是否搜索 CMake 包注册表以查找包。请参见 CMAKE_FIND_USE_PACKAGE_REGISTRY。
CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY: 一个布尔值，指示是否搜索系统 CMake 包注册表以查找包。请参见 CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY。
CMAKE_FIND_ROOT_PATH_MODE: 一个字符串，指示由 CMAKE_FIND_ROOT_PATH_BOTH、ONLY_CMAKE_FIND_ROOT_PATH 和 NO_CMAKE_FIND_ROOT_PATH 参数选择的根路径模式。

候选

被拒绝的候选路径数组。每个元素包含以下键：

路径: 考虑的文件路径。如果是依赖提供者，值为 dependency_provider::<COMMAND_NAME> 形式。
模式: 找到文件的方式。可以是 module、cps、cmake 或 provider 之一。
原因: 路径被拒绝的原因。可以是 insufficient_version、no_exist、ignored、no_config_file 或 not_found 之一。
消息: 如果存在，一个字符串，描述为什么该包被认为未找到。

找到

如果包已找到，则提供有关找到文件的信息。如果未找到，则为 null。可用键：

路径: 找到包的模块或配置的路径。如果是依赖提供者，则值为 dependency_provider::<COMMAND_NAME> 形式。
模式: 考虑路径的模式。可以是 module、cps、cmake 或 provider 之一。
版本: 报告的包版本。

搜索上下文

变量名称到它们指定的搜索路径的映射（根据变量，可以是字符串或字符串数组）。环境变量用 ENV{ 和 } 包裹，否则使用 CMake 变量。只使用指定了任何路径的变量。

包栈

一个对象数组，其中包含由 find_package() 调用提供的路径栈。

包路径: 调用堆栈中 find_package() 命令提供的路径。

cmake-configure-log(7)¶

简介 ¶

日志结构 ¶

日志版本控制 ¶

文本块编码 ¶

事件类型 ¶

事件类型 `message`¶

`message-v1` 事件 ¶

事件类型 `try_compile`¶

`try_compile-v1` 事件 ¶

事件类型 `try_run`¶

`try_run-v1` 事件 ¶

事件类型 `find`¶

`find-v1` 事件 ¶

事件类型 `find_package`¶

`find_package-v1` 事件 ¶

目录

上一主题

下一主题

本页