cmake_instrumentation

Added in version 4.0.

Note

This command is only available when experimental support for instrumentation has been enabled by the CMAKE_EXPERIMENTAL_INSTRUMENTATION gate.

Enables interacting with the CMake Instrumentation API.

This allows for configuring instrumentation at the project-level.

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

The API_VERSION and DATA_VERSION must always be given. Currently, the only supported value for both fields is 1. See API v1 for details of the API_VERSION and Data v1 for details of the DATA_VERSION.

Each of the optional keywords HOOKS, OPTIONS, and CALLBACK correspond to one of the parameters to the v1 Query Files. The CALLBACK keyword can be provided multiple times to create multiple callbacks.

Whenever cmake_instrumentation is invoked, a query file is generated in <build>/.cmake/instrumentation/v1/query/generated to enable instrumentation with the provided arguments.

Custom Configure Content

The CUSTOM_CONTENT argument specifies certain data from configure time to include in each v1 Snippet File that corresponds to the configure step associated with the command. This may be used to associate instrumentation data with certain information about its configuration, such as the optimization level or whether it is part of a coverage build.

CUSTOM_CONTENT expects name, type and content arguments.

name is a specifier to identify the content being reported.

type specifies how the content should be interpreted. Supported values are:

• STRING the content is a string.

• BOOL the content should be interpreted as a boolean. It will be true under the same conditions that if() would be true for the given value.

• LIST the content is a CMake ; separated list that should be parsed.

• JSON the content should be parsed as a JSON string. This can be a number such as 1 or 5.0, a quoted string such as \"string\", a boolean value true/false, or a JSON object such as { \"key\" : \"value\" } that may be constructed using string(JSON ...) commands.

content is the actual content to report.

Example

The following example shows an invocation of the command and its equivalent JSON query file.

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"
  ]
}

This will also result in a configure content JSON being reported in each v1 Snippet File with the following contents:

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