From 515be042e2d31ea1be5d441745d37b76cd42c6b2 Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Mon, 8 Sep 2025 15:55:33 -0400 Subject: [PATCH] Help/instrumentation: Improve formatting * Fix bullet points from commit bf52fbfbc4 (instrumentation: Add Google trace output, 2025-08-28). * Pluralize "v1 Snippet File" where applicable. * Wrap long lines to <80 chars where applicable. --- Help/manual/cmake-instrumentation.7.rst | 56 +++++++++++++------------ 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/Help/manual/cmake-instrumentation.7.rst b/Help/manual/cmake-instrumentation.7.rst index 1f17fee913..69d4f089f7 100644 --- a/Help/manual/cmake-instrumentation.7.rst +++ b/Help/manual/cmake-instrumentation.7.rst @@ -36,12 +36,12 @@ 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 use the -``ctest --instrument`` launcher in order to capture details of each compile, link -and custom command respectively. If the project has been configured with :module:`CTestUseLaunchers`, -``ctest --instrument`` will also include the behavior usually performed by -``ctest --launch``. +CMake sets the :prop_gbl:`RULE_LAUNCH_COMPILE`, :prop_gbl:`RULE_LAUNCH_LINK` +and :prop_gbl:`RULE_LAUNCH_CUSTOM` global properties to use the +``ctest --instrument`` launcher in order to capture details of each compile, +link, and custom command respectively. If the project has been configured with +:module:`CTestUseLaunchers`, ``ctest --instrument`` will also include the +behavior usually performed by ``ctest --launch``. Indexing -------- @@ -346,7 +346,8 @@ and contain the following data: * ``compile``: an individual compile step invoked during the build * ``link``: an individual link step invoked during the build * ``custom``: an individual custom command invoked during the build - * ``build``: a complete ``make`` or ``ninja`` invocation. Only generated if ``preBuild`` or ``postBuild`` hooks are enabled. + * ``build``: a complete ``make`` or ``ninja`` invocation. + Only generated if ``preBuild`` or ``postBuild`` hooks are enabled. * ``cmakeBuild``: a complete ``cmake --build`` invocation * ``cmakeInstall``: a complete ``cmake --install`` invocation * ``install``: an individual ``cmake -P cmake_install.cmake`` invocation @@ -414,9 +415,9 @@ and contain the following data: The Average CPU Load at ``timeStop``. ``configureContent`` - The path to a :ref:`cmake_instrumentation Configure Content` file located under ``data``, - which may contain information about the CMake configure step corresponding - to this data. + The path to a :ref:`cmake_instrumentation Configure Content` file located + under ``data``, which may contain information about the CMake configure + step corresponding to this data. Example: @@ -448,9 +449,10 @@ Example: v1 Index File ------------- -Index files contain a list of `v1 Snippet File`_. It serves as an entry point -for navigating the instrumentation data. They are generated whenever `Indexing`_ -occurs and deleted after any user-specified `Callbacks`_ are executed. +Index files contain a list of `v1 Snippet Files `_. It +serves as an entry point for navigating the instrumentation data. They are +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 @@ -469,9 +471,9 @@ occurs and deleted after any user-specified `Callbacks`_ are executed. ``ctest --collect-instrumentation ``. ``snippets`` - Contains a list of `v1 Snippet File`_. This includes all snippet files - generated since the previous index file was created. The file paths are - relative to ``dataDir``. + Contains a list of `v1 Snippet Files `_. This includes all + snippet files generated since the previous index file was created. The file + paths are relative to ``dataDir``. ``trace``: Contains the path to the `Google Trace File`_. This includes data from all @@ -528,41 +530,41 @@ Google Trace File ----------------- Trace files follow the `Google Trace Event Format`_. They include data from -all `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. +all `v1 Snippet Files `_ 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. Trace files are stored in the ``JSON Array Format``, where each `v1 Snippet File`_ corresponds to a single trace event object. Each trace event contains the following data: - ``name`` +``name`` A descriptive name generated by CMake based on the given snippet data. - ``cat`` +``cat`` The ``role`` from the `v1 Snippet File`_. - ``ph`` +``ph`` Currently, always ``"X"`` to represent ``Complete Events``. - ``ts`` +``ts`` The ``timeStart`` from the `v1 Snippet File`_, converted from milliseconds to microseconds. - ``dur`` +``dur`` The ``duration`` from the `v1 Snippet File`_, converted from milliseconds to microseconds. - ``pid`` +``pid`` Unused (always zero). - ``tid`` +``tid`` An integer ranging from zero to the number of concurrent jobs with which the processes being indexed ran. This is a synthetic ID calculated by CMake based on the ``ts`` and ``dur`` of all snippet files being indexed in order to produce a more useful visualization of the process concurrency. - ``args`` +``args`` Contains all data from the `v1 Snippet File`_ corresponding to this trace event. .. _`Google Trace Event Format`: https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview