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