mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-07 06:09:52 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help/instrumentation: Improve formatting

Browse Source 
* 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.
This commit is contained in:
Tyler Yankee
2025-09-08 15:55:33 -04:00
parent a3a3416bc1
commit 515be042e2
1 changed files with 29 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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 <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.
``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 <build>``.
``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 <v1 Snippet File_>`_. 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 <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.
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