cmake_instrumentation

Added in version 4.0.

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 data output content and location.

Each of the optional keywords HOOKS, QUERIES, and CALLBACK correspond to one of the parameters to the v1 Query Files. Note that the CALLBACK keyword only accepts a single callback.

Whenever cmake_instrumentation is invoked, a query file is generated in <build>/.cmake/timing/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"
)

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