cmake_instrumentation — CMake 4.2.1 Documentation (original) (raw)

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 theCMake Instrumentation API.

This allows for configuring instrumentation at the project-level.

cmake_instrumentation( API_VERSION DATA_VERSION [HOOKS ...] [OPTIONS ...] [CALLBACK ] [CUSTOM_CONTENT ] )

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

Each of the optional keywords HOOKS, OPTIONS, and CALLBACKcorrespond 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 trueunder 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 usingstring(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 eachv1 CMake Content File:

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