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

Help: Make docs for ctest --show-only=json-v1 reflect the implementation

Browse Source 
In elements of the backtraceGraph->nodes array, all but the `file` field
are optional. The documentation implied all fields were mandatory by
not mentioning any of them as optional. Update the docs to make the
optional nature explicit. Use the corresponding documentation for the
CMake file API as a guide for the updated text.

The tests array was also lacking accuracy for which fields were optional
and the tests->properties array didn't specify the type of items that the
array could hold. The explanation for the "config" item was also wrong,
since it always holds the value of the -C option given to ctest. Fix and
expand the docs to address these cases as well.

Fixes: #26965
Issue: #26986
This commit is contained in:
Craig Scott
2025-06-06 17:41:29 +10:00
parent 2121f65c67
commit fe1cd4e157
1 changed files with 31 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
Help/manual/ctest.1.rst
View File

@@ -1619,7 +1619,7 @@ model is defined as follows:
The string "ctestInfo".
``version``
A JSON object specifying the version components. Its members are
A JSON object specifying the version components. Its members are:
``major``
A non-negative integer specifying the major version component.
@@ -1638,32 +1638,50 @@ model is defined as follows:
List of node JSON objects with members:
``command``
Index into the ``commands`` member of the ``backtraceGraph``.
An optional member present when the node represents a command
invocation within the file. The value is an unsigned integer 0-based
index into the ``commands`` member of the ``backtraceGraph``.
``file``
Index into the ``files`` member of the ``backtraceGraph``.
An unsigned integer 0-based index into the ``files`` member of the
``backtraceGraph``.
``line``
Line number in the file where the backtrace was added.
An optional member present when the node represents a line within
the file. The value is an unsigned integer 1-based line number
in the file where the backtrace was added.
``parent``
Index into the ``nodes`` member of the ``backtraceGraph``
representing the parent in the graph.
An optional member present when the node is not the bottom of the
call stack. The value is an unsigned integer 0-based index into the
``nodes`` member of the ``backtraceGraph`` representing the parent
in the graph.
``tests``
A JSON array listing information about each test. Each entry
is a JSON object with members:
``name``
Test name.
Test name. This cannot be empty.
``config``
Configuration that the test can run on.
Empty string means any config.
Optional field specifying the configuration for which the test will run.
This will always match the :option:`-C <ctest -C>` option specified on the
``ctest`` command line. If no such option was given, this field will not
be present.
``command``
List where the first element is the test command and the
remaining elements are the command arguments.
Optional array where the first element is the test command and the
remaining elements are the command arguments. Normally, this field should
be present and non-empty, but in certain corner cases involving generator
expressions, it is possible for a test to have no command and therefore
this field can be missing.
``backtrace``
Index into the ``nodes`` member of the ``backtraceGraph``.
``properties``
Test properties.
Can contain keys for each of the supported test properties.
Optional array of test properties.
Each array item will be a JSON object with the following members:
``name``
The name of the test property. This cannot be empty.
``value``
The property value, which can be a string, a number, a boolean, or an
array of strings.
.. _`ctest-resource-allocation`: