cmake_instrumentation

4.0 版本新增。

注意

此命令仅在通过 CMAKE_EXPERIMENTAL_INSTRUMENTATION 门控启用了实验性支持进行插桩时才可用。

启用与 CMake 插桩 API 的交互。

这允许在项目级别配置插桩。

cmake_instrumentation(
  API_VERSION <version>
  DATA_VERSION <version>
  [HOOKS <hooks>...]
  [OPTIONS <options>...]
  [CALLBACK <callback>]
  [CUSTOM_CONTENT <name> <type> <content>]
)

API_VERSION 和 DATA_VERSION 必须始终提供。目前，两个字段唯一支持的值是 1。有关 API_VERSION 的详细信息，请参阅 API v1，有关 DATA_VERSION 的详细信息，请参阅 Data v1。

可选关键字 HOOKS、OPTIONS 和 CALLBACK 分别对应于 v1 查询文件 的一个参数。可以多次提供 CALLBACK 关键字来创建多个回调。

每当调用 cmake_instrumentation 时，都会在 <build>/.cmake/instrumentation/v1/query/generated 中生成一个查询文件，以使用提供的参数启用插桩。

自定义 CMake 内容

“CUSTOM_CONTENT”参数指定某些配置时的数据，这些数据将包含在每个 v1 CMake 内容文件 中。这可以用于将插桩数据与有关其配置的某些信息关联起来，例如优化级别或它是否是覆盖范围构建的一部分。

CUSTOM_CONTENT 需要 name、type 和 content 参数。

name 是一个标识要报告内容的说明符。

type 指定应如何解释内容。支持的值有：

• STRING：内容是一个字符串。

• BOOL：内容应解释为布尔值。在 if() 会对给定值求真的相同条件下，它将为 true。

• LIST：内容是一个 CMake ; 分隔的列表，应进行解析。

• JSON：内容应解析为 JSON 字符串。这可以是数字（如 1 或 5.0）、带引号的字符串（如 \"string\"）、布尔值 true/false，或 JSON 对象（如 { \"key\" : \"value\" }），该对象可以使用 string(JSON ...) 命令构建。

content 是要报告的实际内容。

示例

以下示例展示了该命令的调用及其等效的 JSON 查询文件。

cmake_instrumentation(
  API_VERSION 1
  DATA_VERSION 1
  HOOKS postGenerate preCMakeBuild postCMakeBuild
  OPTIONS staticSystemInformation dynamicSystemInformation trace
  CALLBACK ${CMAKE_COMMAND} -P /path/to/handle_data.cmake
  CALLBACK ${CMAKE_COMMAND} -P /path/to/handle_data_2.cmake
  CUSTOM_CONTENT myString STRING string
  CUSTOM_CONTENT myList   LIST   "item1;item2"
  CUSTOM_CONTENT myObject JSON   "{ \"key\" : \"value\" }"
)

{
  "version": 1,
  "hooks": [
    "postGenerate", "preCMakeBuild", "postCMakeBuild"
  ],
  "options": [
    "staticSystemInformation", "dynamicSystemInformation", "trace"
  ],
  "callbacks": [
    "/path/to/cmake -P /path/to/handle_data.cmake"
    "/path/to/cmake -P /path/to/handle_data_2.cmake"
  ]
}

这还将导致以下内容包含在每个 v1 CMake 内容文件 中

"custom": {
  "myString": "string",
  "myList": [
    "item1", "item2"
  ],
  "myObject": {
    "key": "value"
  }
}