server-mode: Add debug support

Enable the server to support development with some helper tools:

You can now request debug information with statistics on how
long execution of a command took, how long it took to serialize
the JSON files, and how big the serialized JSON string is.

Also allow to dump results into a file.

1 files changed, 34 insertions, 0 deletions

diff --git a/Help/manual/cmake-server.7.rst b/Help/manual/cmake-server.7.rst
index 7edb6d3..75aa0ee 100644
--- a/Help/manual/cmake-server.7.rst
+++ b/Help/manual/cmake-server.7.rst
@@ -68,6 +68,40 @@ Messages sent to and from the process are wrapped in magic strings::
 The server is now ready to accept further requests via stdin.
 
 
+Debugging
+=========
+
+CMake server mode can be asked to provide statistics on execution times, etc.
+or to dump a copy of the response into a file. This is done passing a "debug"
+JSON object as a child of the request.
+
+The debug object supports the "showStats" key, which takes a boolean and makes
+the server mode return a "zzzDebug" object with stats as part of its response.
+"dumpToFile" takes a string value and will cause the cmake server to copy
+the response into the given filename.
+
+This is a response from the cmake server with "showStats" set to true::
+
+  [== CMake Server ==[
+  {
+    "cookie":"",
+    "errorMessage":"Waiting for type \"handshake\".",
+    "inReplyTo":"unknown",
+   "type":"error",
+    "zzzDebug": {
+      "dumpFile":"/tmp/error.txt",
+      "jsonSerialization":0.011016,
+      "size":111,
+      "totalTime":0.025995
+    }
+  }
+  ]== CMake Server ==]
+
+The server has made a copy of this response into the file /tmp/error.txt and
+took 0.011 seconds to turn the JSON response into a string, and it took 0.025
+seconds to process the request in total. The reply has a size of 111 bytes.
+
+
 Protocol API
 ============