mirror of
https://gitlab.kitware.com/cmake/cmake.git
synced 2026-09-25 04:09:36 +03:00
120 lines
3.7 KiB
ReStructuredText
120 lines
3.7 KiB
ReStructuredText
cmake_instrumentation
|
|
---------------------
|
|
|
|
.. versionadded:: 4.3
|
|
|
|
Enables interacting with the
|
|
:manual:`CMake Instrumentation API <cmake-instrumentation(7)>`.
|
|
|
|
This allows for configuring instrumentation at the project-level.
|
|
|
|
.. code-block:: cmake
|
|
|
|
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.
|
|
|
|
``API_VERSION`` is an integer. Currently, the only supported value is ``1``.
|
|
See :ref:`cmake-instrumentation API v1` for details.
|
|
|
|
``DATA_VERSION`` is a version value of the form ``major`` or ``major.minor``.
|
|
Currently, the maximum supported version is ``1.2``. See
|
|
:ref:`cmake-instrumentation Data Version` for details.
|
|
|
|
Each of the optional keywords ``HOOKS``, ``OPTIONS``, and ``CALLBACK``
|
|
correspond to one of the parameters to the :ref:`cmake-instrumentation 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.
|
|
|
|
.. _`cmake_instrumentation CUSTOM_CONTENT`:
|
|
|
|
Custom CMake Content
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
The ``CUSTOM_CONTENT`` argument specifies certain data from configure time to
|
|
include in each :ref:`cmake-instrumentation 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.
|
|
|
|
.. code-block:: cmake
|
|
|
|
cmake_instrumentation(
|
|
API_VERSION 1
|
|
DATA_VERSION 1.2
|
|
HOOKS postGenerate preCMakeBuild postCMakeBuild
|
|
OPTIONS staticSystemInformation dynamicSystemInformation compileTrace 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\" }"
|
|
)
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"version": {
|
|
"major": 1,
|
|
"minor": 2
|
|
},
|
|
"hooks": [
|
|
"postGenerate", "preCMakeBuild", "postCMakeBuild"
|
|
],
|
|
"options": [
|
|
"staticSystemInformation", "dynamicSystemInformation", "compileTrace", "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
|
|
:ref:`cmake-instrumentation v1 CMake Content File`:
|
|
|
|
.. code-block:: json
|
|
|
|
"custom": {
|
|
"myString": "string",
|
|
"myList": [
|
|
"item1", "item2"
|
|
],
|
|
"myObject": {
|
|
"key": "value"
|
|
}
|
|
}
|