mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-05-07 22:59:56 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'instrumentation-ctest-interface'

Browse Source 
21ac285cd8 Experimental: Update the Instrumentation UUID
9dec460c8c instrumentation: Store CDash settings in query files
afa94bae1e instrumentation: Rename queries field to options

Acked-by: Kitware Robot <kwrobot@kitware.com>
Tested-by: buildbot <buildbot@kitware.com>
Merge-request: !10934
This commit is contained in:
Brad King
2025-07-21 14:13:11 +00:00
committed by Kitware Robot
parent f8dcf102d9 21ac285cd8
commit 5e26f8d3a7
36 changed files with 255 additions and 195 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Help/command/cmake_instrumentation.rst
+4 -4
View File
@@ -19,7 +19,7 @@ This allows for configuring instrumentation at the project-level.
API_VERSION <version>
DATA_VERSION <version>
[HOOKS <hooks>...]
[QUERIES <queries>...]
[OPTIONS <options>...]
[CALLBACK <callback>]
)
@@ -28,7 +28,7 @@ only supported value for both fields is 1. See :ref:`cmake-instrumentation API
for details of the ``API_VERSION`` and :ref:`cmake-instrumentation Data v1` for details
of the ``DATA_VERSION``.
Each of the optional keywords ``HOOKS``, ``QUERIES``, and ``CALLBACK``
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.
@@ -48,7 +48,7 @@ equivalent JSON query file.
API_VERSION 1
DATA_VERSION 1
HOOKS postGenerate preCMakeBuild postCMakeBuild
QUERIES staticSystemInformation dynamicSystemInformation
OPTIONS staticSystemInformation dynamicSystemInformation
CALLBACK ${CMAKE_COMMAND} -P /path/to/handle_data.cmake
CALLBACK ${CMAKE_COMMAND} -P /path/to/handle_data_2.cmake
)
@@ -60,7 +60,7 @@ equivalent JSON query file.
"hooks": [
"postGenerate", "preCMakeBuild", "postCMakeBuild"
],
"queries": [
"options": [
"staticSystemInformation", "dynamicSystemInformation"
],
"callbacks": [
Help/dev/experimental.rst
+4 -4
View File
@@ -127,15 +127,15 @@ In order to activate support for the :command:`cmake_instrumentation` command,
set
* variable ``CMAKE_EXPERIMENTAL_INSTRUMENTATION`` to
* value ``a37d1069-1972-4901-b9c9-f194aaf2b6e0``.
* value ``d16a3082-c4e1-489b-b90c-55750a334f27``.
To enable instrumentation at the user-level, files should be placed under
either
``<CMAKE_CONFIG_DIR>/instrumentation-a37d1069-1972-4901-b9c9-f194aaf2b6e0`` or
``<CMAKE_BINARY_DIR>/.cmake/instrumentation-a37d1069-1972-4901-b9c9-f194aaf2b6e0``.
``<CMAKE_CONFIG_DIR>/instrumentation-d16a3082-c4e1-489b-b90c-55750a334f27`` or
``<CMAKE_BINARY_DIR>/.cmake/instrumentation-d16a3082-c4e1-489b-b90c-55750a334f27``.
To include instrumentation data in CTest XML files (for submission to CDash),
you need to set the following environment variables:
* ``CTEST_USE_INSTRUMENTATION=1``
* ``CTEST_EXPERIMENTAL_INSTRUMENTATION=a37d1069-1972-4901-b9c9-f194aaf2b6e0``
* ``CTEST_EXPERIMENTAL_INSTRUMENTATION=d16a3082-c4e1-489b-b90c-55750a334f27``
Help/manual/cmake-instrumentation.7.rst
+36 -15
View File
@@ -100,7 +100,7 @@ Enabling Instrumentation for CDash Submissions
You can enable instrumentation when using CTest in :ref:`Dashboard Client`
mode by setting the :envvar:`CTEST_USE_INSTRUMENTATION` environment variable
to the current UUID for the ``CMAKE_EXPERIMENTAL_INSTRUMENTATION`` feature.
Doing so automatically enables the ``dynamicSystemInformation`` query.
Doing so automatically enables the ``dynamicSystemInformation`` option.
The following table shows how each type of instrumented command gets mapped
to a corresponding type of CTest XML file.
@@ -125,6 +125,9 @@ By default the command line reported to CDash is truncated at the first space.
You can instead choose to report the full command line (including arguments)
by setting :envvar:`CTEST_USE_VERBOSE_INSTRUMENTATION` to 1.
Alternatively, you can use the `v1 Query Files`_ to enable instrumentation for
CDash using the ``cdashSubmit`` and ``cdashVerbose`` options.
.. _`cmake-instrumentation API v1`:
API v1
@@ -146,8 +149,9 @@ subdirectories:
``query/generated/``
Holds query files generated by a CMake project with the
:command:`cmake_instrumentation` command. These files are owned by CMake and
are deleted and regenerated automatically during the CMake configure step.
:command:`cmake_instrumentation` command or the
:envvar:`CTEST_USE_INSTRUMENTATION` variable. These files are owned by CMake
and are deleted and regenerated automatically during the CMake configure step.
``data/``
Holds instrumentation data collected on the project. CMake owns all data
@@ -192,9 +196,10 @@ key is required, but all other fields are optional.
* ``postInstall``
* ``postTest``
``queries``
A list of strings specifying additional optional data to collect during
instrumentation. Elements in this list should be one of the following:
``options``
A list of strings used to enable certain optional behavior, including the
collection of certain additional data. Elements in this list should be one of
the following:
``staticSystemInformation``
Enables collection of the static information about the host machine CMake
@@ -207,13 +212,26 @@ key is required, but all other fields are optional.
generated by CMake, and includes information from immediately before and
after the command is executed.
``cdashSubmit``
Enables including instrumentation data in CDash. This does not
automatically enable ``dynamicSystemInformation``, but is otherwise
equivalent to having the :envvar:`CTEST_USE_INSTRUMENTATION` environment
variable enabled.
``cdashVerbose``
Enables including the full untruncated commands in data submitted to
CDash. Equivalent to having the
:envvar:`CTEST_USE_VERBOSE_INSTRUMENTATION` environment variable enabled.
The ``callbacks`` listed will be invoked during the specified hooks
*at a minimum*. When there are multiple query files, the ``callbacks``,
``hooks`` and ``queries`` between them will be merged. Therefore, if any query
``hooks`` and ``options`` between them will be merged. Therefore, if any query
file includes any ``hooks``, every ``callback`` across all query files will be
executed at every ``hook`` across all query files. Additionally, if any query
file includes any optional ``queries``, the optional query data will be present
in all data files.
file requests optional data using the ``options`` field, any related data will
be present in all snippet files. User written ``callbacks`` should be able to
handle the presence of this optional data, since it may be requested by an
unrelated query.
Example:
@@ -229,9 +247,10 @@ Example:
"postCMakeBuild",
"postInstall"
],
"queries": [
"options": [
"staticSystemInformation",
"dynamicSystemInformation"
"dynamicSystemInformation",
"cdashSubmit"
]
}
@@ -240,12 +259,14 @@ invocation, an index file ``index-<timestamp>.json`` will be generated in
``<build>/.cmake/instrumentation/v1/data`` containing a list of data snippet
files created since the previous indexing. The commands
``/usr/bin/python callback.py index-<timestamp>.json`` and
``/usr/bin/cmake -P callback.cmake arg index-<timestamp>.json`` will be executed in
that order. The index file will contain the ``staticSystemInformation`` data and
each snippet file listed in the index will contain the
``/usr/bin/cmake -P callback.cmake arg index-<timestamp>.json`` will be executed
in that order. The index file will contain the ``staticSystemInformation`` data
and each snippet file listed in the index will contain the
``dynamicSystemInformation`` data. Once both callbacks have completed, the index
file and all snippet files listed by it will be deleted from the project build
tree.
tree. The instrumentation data will be present in the XML files submitted to
CDash, but with truncated command strings because ``cdashVerbose`` was not
enabled.
.. _`cmake-instrumentation Data v1`: