From 1d0f587062fe1edcc1eeea8efdbd83d288e2a736 Mon Sep 17 00:00:00 2001 From: Martin Duffy Date: Wed, 20 May 2026 13:45:52 -0400 Subject: [PATCH] instrumentation: Clarify API and Data version distinction The instrumentation docs were unclear about the difference between API and Data version, with the hierarchy of the table of contents being particularly misleading. Rework `cmake-instrumentation` manual and `cmake_instrumentation` command documentation to be more clear. --- Help/command/cmake_instrumentation.rst | 6 +- Help/manual/cmake-instrumentation.7.rst | 74 +++++++++++++++---------- 2 files changed, 48 insertions(+), 32 deletions(-) diff --git a/Help/command/cmake_instrumentation.rst b/Help/command/cmake_instrumentation.rst index 4e2aa43ef1..3cd7febacc 100644 --- a/Help/command/cmake_instrumentation.rst +++ b/Help/command/cmake_instrumentation.rst @@ -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`. diff --git a/Help/manual/cmake-instrumentation.7.rst b/Help/manual/cmake-instrumentation.7.rst index 582adf8e42..a9b1e141c0 100644 --- a/Help/manual/cmake-instrumentation.7.rst +++ b/Help/manual/cmake-instrumentation.7.rst @@ -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 ` 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 ` 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 ``/.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 ``--.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``