diff options
| author | Braulio Valdivielso Martinez <bvaldivielso@bloomberg.net> | 2022-02-04 17:19:32 (GMT) |
|---|---|---|
| committer | Braulio Valdivielso Martinez <bvaldivielso@bloomberg.net> | 2022-02-07 21:03:22 (GMT) |
| commit | a41d6e4d7a264954bebd6c1c45475647da60e14c (patch) | |
| tree | c080acd8e9a85ae4b43387ae2ec9f380bf6af382 /Help | |
| parent | ca4bb89f276e244b5b56d1988cd659d30df1ca5a (diff) | |
| download | CMake-a41d6e4d7a264954bebd6c1c45475647da60e14c.zip CMake-a41d6e4d7a264954bebd6c1c45475647da60e14c.tar.gz CMake-a41d6e4d7a264954bebd6c1c45475647da60e14c.tar.bz2 | |
Trace: add global_frame field to json-v1 format
Tools using the json-v1 format might want to trace stack frames across
different `CMakeLists.txt` files, in order to, for example, provide
stacktraces that span from the top-level `CMakeLists.txt` in a
project. One would think that `frame` lets you do that, but it
doesn't, because it tells you the depth of the stack within the
current `CMakeLists.txt`, so it gets reset across calls to
`add_subdirectory`.
The solution involves adding a field with a "global frame". This value
gets incremented on calls to `add_subdirectory`, which makes it easier
for tools to reconstruct "global stacktraces".
I considered changing the current "frame" value, but I didn't because
it would be a breaking change. I cannot think of any use-case where
"frame" is more useful to "global-frame", but maybe I'm missing
something.
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/manual/cmake.1.rst | 13 | ||||
| -rw-r--r-- | Help/release/dev/trace-global-frame.rst | 8 |
2 files changed, 18 insertions, 3 deletions
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index c2b4d68..2102b36 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -298,7 +298,8 @@ Options "cmd": "add_executable", "args": ["foo", "bar"], "time": 1579512535.9687231, - "frame": 2 + "frame": 2, + "global_frame": 4 } The members are: @@ -325,7 +326,13 @@ Options Timestamp (seconds since epoch) of the function call. ``frame`` - Stack frame depth of the function that was called. + Stack frame depth of the function that was called, within the + context of the ``CMakeLists.txt`` being processed currently. + + ``global_frame`` + Stack frame depth of the function that was called, tracked globally + across all ``CMakeLists.txt`` files involved in the trace. This field + was added in minor version 2 of the ``json-v1`` format. Additionally, the first JSON document outputted contains the ``version`` key for the current major and minor version of the @@ -337,7 +344,7 @@ Options { "version": { "major": 1, - "minor": 1 + "minor": 2 } } diff --git a/Help/release/dev/trace-global-frame.rst b/Help/release/dev/trace-global-frame.rst new file mode 100644 index 0000000..fdc4b5c --- /dev/null +++ b/Help/release/dev/trace-global-frame.rst @@ -0,0 +1,8 @@ +trace-global-frame +------------------ + +* Add the field ``global_frame`` to the json-v1 trace format. This + frame tracks the depth of the call stack globally across all + ``CMakeLists.txt`` files involved in the trace, and will let tools + reconstruct stack traces that span from the top-level ``CMakeLists.txt`` + file of the project. |