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>...]
  [QUERIES <queries>...]
  [CALLBACK <callback>]
)

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, QUERIES, 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.

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
  QUERIES staticSystemInformation dynamicSystemInformation
  CALLBACK ${CMAKE_COMMAND} -P /path/to/handle_data.cmake
  CALLBACK ${CMAKE_COMMAND} -P /path/to/handle_data_2.cmake
)

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