# cmake_instrumentation

Added in version 4.3.

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 Version 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 CMake Content

The `CUSTOM_CONTENT` argument specifies certain data from configure time to include in each v1 CMake Content File. 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 the following content included in each v1 CMake Content File:

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