trace: Add JSON output format

Add a new `--trace-format=` flag, to enable the new JSON trace
output format. This new format is easier to parse by machines
than the existing format. This new format also removes the
ambiguity of the whitespace in the "old" format (e.g. is that
whitespace part of a file path, or does it seperate arguments)

2 files changed, 67 insertions, 0 deletions

diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 6f33866..bae64f7 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -251,6 +251,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.