Merge topic 'traceJSON'

e113ab1168 trace: Add test for the JSON-v1 trace
482497e0de trace: Add JSON output format

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !4102

2 files changed, 67 insertions, 0 deletions

diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index f8847f1..4315f0a 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -257,6 +257,66 @@ Options
 
  Like ``--trace``, but with variables expanded.
 
+``--trace-format=<format>``
+ Put cmake in trace mode and sets the trace output format.
+
+ ``<format>`` can be one of the following values.
+
+   ``human``
+     Prints each trace line in a human-readable format. This is the
+     default format.
+
+   ``json``
+     Prints each line as a separate JSON document. Each document is
+     separated by a newline ( ``\n`` ). It is guaranteed that no
+     newline characters will be present inside a JSON document.
+
+     JSON trace format:
+
+     .. code-block:: json
+
+       {
+         "file": "/full/path/to/the/CMake/file.txt",
+         "line": 0,
+         "cmd": "add_executable",
+         "args": ["foo", "bar"]
+       }
+
+     The members are:
+
+     ``file``
+       The full path to the CMake source file where the function
+       was called.
+
+      ``line``
+       The line in `file` of the function call.
+
+     ``cmd``
+       The name of the function that was called.
+
+     ``args``
+       A string list of all function parameters.
+
+     Additionally, the first JSON document outputted contains the
+     ``version`` key for the current major and minor version of the
+
+     JSON trace format:
+
+     .. code-block:: json
+
+       {
+         "version": {
+           "major": 1,
+           "minor": 0
+         }
+       }
+
+     The members are:
+
+     ``version``
+       Indicates the version of the JSON format. The version has a
+       major and minor components following semantic version conventions.
+
 ``--trace-source=<file>``
  Put cmake in trace mode, but output only lines of a specified file.
 
diff --git a/Help/release/dev/json_trace.rst b/Help/release/dev/json_trace.rst
new file mode 100644
index 0000000..69a1fb7
--- /dev/null
+++ b/Help/release/dev/json_trace.rst
@@ -0,0 +1,7 @@
+json-trace
+----------
+
+* :manual:`cmake(1)` gained a ``--trace-format`` command line option that
+  can be used to set the ``--trace`` output format. Currently, the old
+  human readable and the new JSON format are supported. The new JSON format
+  is easier to parse automatically, than the existing format.