dilim/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-08-04 23:00:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'instrumentation-data-version-doc'

Browse Source 
1d0f587062 instrumentation: Clarify API and Data version distinction

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !12091
This commit is contained in:
Brad King
2026-05-21 13:45:04 +00:00
committed by Kitware Robot
parent d7c0609e0d 1d0f587062
commit 0d2e9ce13c
2 changed files with 48 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
Help/command/cmake_instrumentation.rst
View File

@@ -20,9 +20,9 @@ This allows for configuring instrumentation at the project-level.
)
The ``API_VERSION`` and ``DATA_VERSION`` must always be given. Currently, the
only supported value for both fields is 1. See :ref:`cmake-instrumentation API v1`
for details of the ``API_VERSION`` and :ref:`cmake-instrumentation Data v1` for details
of the ``DATA_VERSION``.
only supported value for both fields is 1. See
:ref:`cmake-instrumentation API v1` for details of the ``API_VERSION`` and
:ref:`cmake-instrumentation 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 :ref:`cmake-instrumentation v1 Query Files`.

74
Help/manual/cmake-instrumentation.7.rst
View File

@@ -18,7 +18,7 @@ build, test and install steps for a CMake project.
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`_.
these: see the `API v1`_ and `Data Version`_.
.. note::
@@ -139,21 +139,21 @@ environment variable. Doing so automatically enables the
The following table shows how each type of instrumented command gets mapped
to a corresponding type of CTest XML file.
=================================================== ==================
:ref:`Snippet Role <cmake-instrumentation Data v1>` CTest XML File
=================================================== ==================
``configure`` ``Configure.xml``
``generate`` ``Configure.xml``
``compile`` ``Build.xml``
``link`` ``Build.xml``
``custom`` ``Build.xml``
``build`` unused!
``cmakeBuild`` ``Build.xml``
``cmakeInstall`` ``Build.xml``
``install`` ``Build.xml``
``ctest`` ``Build.xml``
``test`` ``Test.xml``
=================================================== ==================
=========================================================== ==================
:ref:`Snippet Role <cmake-instrumentation v1 Snippet File>` CTest XML File
=========================================================== ==================
``configure`` ``Configure.xml``
``generate`` ``Configure.xml``
``compile`` ``Build.xml``
``link`` ``Build.xml``
``custom`` ``Build.xml``
``build`` unused!
``cmakeBuild`` ``Build.xml``
``cmakeInstall`` ``Build.xml``
``install`` ``Build.xml``
``ctest`` ``Build.xml``
``test`` ``Test.xml``
=========================================================== ==================
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)
@@ -216,6 +216,23 @@ subdirectories:
Holds temporary files used internally to generate XML content to be submitted
to CDash.
.. _`cmake-instrumentation Data Version`:
Data Version
------------
The data version specifies the contents of the output files generated by the
`API v1`_ as part of the `Data Collection`_ and `Indexing`_ processes.
`v1 Query Files`_, or a :command:`cmake_instrumentation` invocation, should
request a specific Data Version, and `v1 Data Files`_ of the corresponding
version will be generated and sent to the user `Callbacks`_ defined in that
query.
Currently, the only supported version is ``1``. A new version number will be
created whenever previously included data is removed or reformatted such that
scripts written to parse this data may become incompatible with the new format.
.. _`cmake-instrumentation v1 Query Files`:
v1 Query Files
@@ -228,7 +245,7 @@ These files must contain a JSON object with the following keys. The ``version``
key is required, but all other fields are optional.
``version``
The Data version of snippet file to generate, an integer. Currently the only
The `Data Version`_ of snippet file to generate, an integer. Currently the only
supported version is ``1``.
``callbacks``
@@ -338,20 +355,19 @@ 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`:
v1 Data Files
-------------
Data v1
=======
Data version specifies the contents of the output files generated by the CMake
instrumentation API as part of the `Data Collection`_ and `Indexing`_. A new
version number will be created whenever previously included data is removed or
reformatted such that scripts written to parse this data may become
incompatible with the new format. There are four types of data files generated:
There are four types of data files generated as part of `API v1`_:
the `v1 Snippet File`_, `v1 Index File`_, `v1 CMake Content File`_, and the
`Google Trace File`_. When using the `API v1`_, these files live in
`Google Trace File`_. These files live in
``<build>/.cmake/instrumentation/v1/data/`` under the project build tree.
Note that the ``v1`` delineation of these files refers to the `API v1`_.
The `Data Version`_ of these files is specified with a ``version`` field as
part of the file contents.
.. _`cmake-instrumentation v1 Snippet File`:
v1 Snippet File
@@ -386,7 +402,7 @@ Snippet files have a filename with the syntax
``<role>-<hash>-<timestamp>.json`` and contain the following data:
``version``
The Data version of the snippet file, an integer. Currently the version is
The `Data Version`_ of the snippet file, an integer. Currently the version is
always ``1``.
``command``
@@ -522,7 +538,7 @@ generated whenever `Indexing`_ occurs and deleted after any user-specified
`Callbacks`_ are executed.
``version``
The Data version of the index file, an integer. Currently the version is
The `Data Version`_ of the index file, an integer. Currently the version is
always ``1``.
``buildDir``