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 对象版本，然后仅按照文件 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>) 的位置的字符串。
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 映射的键是：

描述

当使用了 LOG_DESCRIPTION <text> 选项时，存在一个可选键。其值为一个字符串，包含描述 <text>。

directories

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

源: 一个字符串，指定 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

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

事件类型 `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 映射的键是：

mode

一个字符串，描述了使用搜索的命令。可能是 file、path、program 或 library。

variable

搜索将其结果存储到的变量。

描述

变量的文档字符串。

settings

搜索中生效的搜索设置。

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。

names

用于查询查找的名称。

candidate_directories

在搜索过程中要查找的候选目录，按顺序排列。

searched_directories

在搜索过程中要查找的目录，按顺序排列。

found

要么是表示找到的值的字符串，要么是 false，如果未找到。

search_context

一个变量名到其指定路径的映射（根据变量是字符串或字符串数组）。环境变量用 ENV{ 和 } 包装，否则使用 CMake 变量。仅使用任何路径指定的变量。

package_stack

来自 find_package() 调用提供的路径对象数组。

package_paths: 来自调用堆栈中的 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 映射的键是：

名称

请求的包的名称。

组件

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

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

configs

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

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

version_request

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

版本: 所需的最小版本。
version_complete: 用户提供的版本范围。
min: 是 INCLUDE 还是 EXCLUDE 版本范围的下界。
max: 是 INCLUDE 还是 EXCLUDE 版本范围的上界。
exact: 一个布尔值，指示是否请求了 EXACT 版本匹配。

settings

搜索中生效的搜索设置。

required

搜索的要求。可能是 optional、optional_explicit、required_explicit、required_from_package_variable 或 required_from_find_variable。

quiet

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

global

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

policy_scope

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

bypass_provider

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

hints

作为 HINTS 提供的路径数组。

names

用于搜索的包名数组，由 NAMES 提供。

search_paths

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

path_suffixes

由 PATH_SUFFIXES 提供的搜索路径后缀数组。

registry_view

为搜索请求的 REGISTRY_VIEW。

paths

搜索中生效的路径设置。

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 参数选择的根路径模式。

candidates

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

path: 被考虑的文件路径。对于依赖项提供程序，值为 dependency_provider::<COMMAND_NAME> 形式。
mode: 找到文件的模式。可能是 module、cps、cmake 或 provider。
reason: 拒绝路径的原因。可能是 insufficient_version、no_exist、ignored、no_config_file 或 not_found。
message: 如果存在，则为描述为什么该包被视为未找到的字符串。

found

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

path: 找到该包的模块或配置的路径。对于依赖项提供程序，值为 dependency_provider::<COMMAND_NAME> 形式。
mode: 考虑该路径的模式。可能是 module、cps、cmake 或 provider。
版本: 报告的包版本。

search_context

一个变量名到其指定路径的映射（根据变量是字符串或字符串数组）。环境变量用 ENV{ 和 } 包装，否则使用 CMake 变量。仅使用任何路径指定的变量。

package_stack

来自 find_package() 调用提供的路径对象数组。

package_paths: 来自调用堆栈中的 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` 事件¶

目录

上一主题

下一主题

本页

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 事件¶

引言 ¶

日志结构 ¶

日志版本控制 ¶

文本块编码 ¶

事件类型 ¶

事件类型 `message`¶

`message-v1` 事件¶

事件类型 `try_compile`¶

`try_compile-v1` 事件¶

事件类型 `try_run`¶

`try_run-v1` 事件¶

事件类型 `find`¶

`find-v1` 事件¶

事件类型 `find_package`¶

`find_package-v1` 事件¶