mirrors/cmake
2
0 Fork 0
mirror of https://gitlab.kitware.com/cmake/cmake.git synced 2026-10-08 23:44:00 +03:00
Code Activity

Help/instrumentation: Improve CMake Instrumentation documentation

Browse Source 
Fixes: #27688
This commit is contained in:
Martin Duffy committed 2026-03-24 17:09:38 -04:00
1 parent 7178780043
commit b8d8faf900
1 file changed
+66 -22
Download Patch File Download Diff File Expand all files Collapse all files
Help/manual/cmake-instrumentation.7.rst
+66 -22
View File
@@ -16,20 +16,41 @@ The CMake Instrumentation API allows for the collection of timing data, target
information and system diagnostic information during the configure, generate,
build, test and install steps for a CMake project.
This feature is only available for projects using the
:ref:`Makefile Generators`, :ref:`Ninja Generators` or :generator:`FASTBuild`.
All interactions with the CMake instrumentation API must specify both an API
version and a Data version. At this time, there is only one version for each of
these: the `API v1`_ and `Data v1`_.
.. note::
This feature is only available for projects using the
:ref:`Makefile Generators`, :ref:`Ninja Generators` or :generator:`FASTBuild`.
Overview
--------
CMake Instrumentation works in 2 major stages: `Data Collection`_, and
`Indexing`_.
`Data Collection`_ is the process by which CMake writes out instrumentation
data into a project build tree. The commands instrumented in this way range
from overall builds, to individual compile commands. The full list of commands
instrumented is documented under the `v1 Snippet File`_.
Collected data will accumulate until `Indexing`_ occurs: the process of
collating the generated data. Indexing occurs on events called "hooks",
which can be configured as part of the `v1 Query Files`_. A `v1 Index File`_ is
created and passed to any user-defined `Callbacks`_ provided to process
the data. Once all `Callbacks`_ have run, CMake deletes the files.
Without the need for any custom `Callbacks`_, CMake can submit instrumentation
data to `CDash`_, or generate a `Google Trace File`_ for visualization.
Data Collection
---------------
Whenever a command is executed with
instrumentation enabled, a `v1 Snippet File`_ is created in the project build
tree with data specific to that command. These files remain until after
`Indexing`_ occurs.
Whenever a command is executed with instrumentation enabled, a
`v1 Snippet File`_ is created in the project build tree with data specific to
that command. These files remain until after `Indexing`_ occurs.
CMake sets the :prop_gbl:`RULE_LAUNCH_COMPILE`, :prop_gbl:`RULE_LAUNCH_LINK`
and :prop_gbl:`RULE_LAUNCH_CUSTOM` global properties to wrap each compile, link
@@ -43,11 +64,12 @@ addition to performing the communication typically handled by that module.
Indexing
--------
Indexing is the process of collating generated instrumentation data. Indexing
occurs at specific intervals called hooks, such as after every build. These
hooks are configured as part of the `v1 Query Files`_. Whenever a hook is
triggered, an index file is generated containing a list of snippet files newer
than the previous indexing.
Indexing is the process of collating generated instrumentation data. The
available hooks to trigger indexing include options such as after every build,
or every :manual:`ctest <ctest(1)>` invocation, and are configured as part of the `v1 Query Files`_.
Whenever a hook is triggered, an index file is generated containing a list of
snippet files newer than the previous indexing. This index file is passed to
user-defined `Callbacks`_ commands to process the data.
Indexing and can also be performed by manually invoking
:option:`ctest --collect-instrumentation`.
@@ -55,31 +77,36 @@ Indexing and can also be performed by manually invoking
.. _`cmake-instrumentation Callbacks`:
Callbacks
---------
^^^^^^^^^
As part of the `v1 Query Files`_, users can provide a list of callbacks
intended to handle data collected by this feature.
Whenever `Indexing`_ occurs, each provided callback is executed, passing the
path to the generated index file as an argument.
path to the generated `v1 Index File`_ as an additional argument.
These callbacks, defined either at the user-level or project-level should read
These callbacks, defined either at the user-level or project-level, should read
the instrumentation data and perform any desired handling of it. The index file
and its listed snippets are automatically deleted by CMake once all callbacks
have completed. Note that a callback should never move or delete these data
files manually as they may be needed by other callbacks.
If indexing is triggered again before `Callbacks`_ have finished running,
the generated index file will contain only instrumentation data generated since
the previous indexing.
Enabling Instrumentation
========================
Instrumentation can be enabled either for an individual CMake project, or
for all CMake projects configured and built by a user. For both cases,
see the `v1 Query Files`_ for details on configuring this feature.
for all CMake projects configured and built by a user. In all cases, a "query"
represents a request for instrumentation behavior. See the `v1 Query Files`_
for details on configuring this feature.
Enabling Instrumentation at the Project-Level
---------------------------------------------
Project code can contain instrumentation queries with the
Project code can contain instrumentation queries by using the
:command:`cmake_instrumentation` command.
In addition, query files can be placed manually under
@@ -93,6 +120,8 @@ Instrumentation can be configured at the user-level by placing query files in
the :envvar:`CMAKE_CONFIG_DIR` under
``<config_dir>/instrumentation/<version>/query/``.
.. _`CDash`:
Enabling Instrumentation for CDash Submissions
----------------------------------------------
@@ -502,11 +531,19 @@ generated whenever `Indexing`_ occurs and deleted after any user-specified
value may be set to ``manual`` if indexing is performed by invoking
:option:`ctest --collect-instrumentation`.
Note that the hook is not directly tied to what data may be available.
A ``postBuild`` hook, for example, may include ``test`` or ``install``
snippets, if these steps were run since the previous indexing.
``snippets``
Contains a list of `v1 Snippet Files <v1 Snippet File_>`_. This includes all
snippet files generated since the previous index file was created. The file
paths are relative to ``dataDir``.
This list may be empty if indexing was run twice in succession, such as when
building multiple times with both the ``preBuild`` and ``postBuild`` hooks
enabled.
``trace``
Contains the path to the `Google Trace File`_. This includes data from all
corresponding ``snippets`` in the index file. The file path is relative to
@@ -599,10 +636,17 @@ Each CMake content file contains the following:
Google Trace File
-----------------
Trace files follow the `Google Trace Event Format`_. They include data from
all `v1 Snippet Files <v1 Snippet File_>`_ listed in the current index file.
These files remain in the build tree even after `Indexing`_ occurs and all
`Callbacks`_ are executed, until the next time `Indexing`_ occurs.
CMake can generate a file in the `Google Trace Event Format`_ to help visualize
collected instrumentation data. Enabling the ``trace`` option in the
`v1 Query Files`_ causes such a file to be generated under
``<build>/.cmake/v1/instrumentation/data/trace`` whenever `Indexing`_ occurs.
Generated trace files include data from all
`v1 Snippet Files <v1 Snippet File_>`_ listed in the current index file.
When instrumentation data is deleted by CMake after `Indexing`_, the most
recent trace file remains so that it can be manually inspected without the need
for any custom `Callbacks`_.
Trace files are stored in the ``JSON Array Format``, where each
`v1 Snippet File`_ corresponds to a single trace event object. Each trace