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 9fe2d3c8c5..583eb710ec 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``