[cmake-developers] cmake daemon mode protocol

[Tobias Hunger]

Hi Stephen,

I have successfully build and run your cmake server mode changes and
the python client script does work as advertised.

I do have a couple of remarks about it. This is more intended as a
starting point for discussion as a real proposal. Would something
along these lines be possible:

* Start daemon-mode without any additional parameters

* Daemon responds with "
  {
    "type": "handShake",
    "version": "3.5.x",
    "supportedProtocols": "3.5"
  }

* Client Handshake:
  {
    "type": "handshake",
    "requestProtocolVersion": "3.5"
  }

* Daemon:
  {
    "type:"handshake",
    "protocolVersion": "3.5"
  }


At this point the normal operation should be possible.

* Client:
  {
     "type": "setProjectInformation",
     "sourceDirectory": "/some/path",
     "cookie": "1"
  }

  Being able to set the source directory is important so that a fresh
checkout can be configured. There is no build directory available at
that time...

* Daemon should do progress handling while reading the CMakeLists.txt
or whatever it does:
  { "type": "progress", "state": "busy", "task": "someId",
"taskDescription": "Reading CMakeLists.txt files", "cookie": "1" }

* Daemon sends occasional:
  { "type": "progress", "task": "someId", progressTotal: 25,
progressCurrent: 12, "cookie": "1" }

* Daemon sends (probably optional...):
  { "type": "progress", "task": "someId", "state": "done", "cookie": "1" }

* Finally Daemon responds sends data as that is available now.
  {
    "type": "projectInformation",
    "sourceDirectory": "/some/path",
    "buildDirectory": "",
    "projectName": "SomeProject",
    "cookie": "1"
  }

* Client:
  {
    "type": "setProjectInformation",
    "buildDirectory": "/some/other/path",
    "cookie": "2"
  }

* Daemon does progress indication as above...

* Daemon responds with project info:
  {
    "type": "progressInformation",
    "sourceDirectory": "/some/path",
    "buildDirectory": "/some/other/path",
    "projectName": "SomeProject",
    "cookie": "2"
  }

We might also want a "ping"/"pong" to detect if the daemon is still
responding. That would require the daemon to be able to handle
multiple requests to be in flight... not sure that this is worth it.
But if we can not do that, then we need to provide constant progress
information, which is also not great:-)

Not sure about the need for cookies (text set by the client and
repeated by the server in all its replies to that request). I do think
having them makes sense, even when only one request can be active at
any time: They make it so much easier to sanity-check communication.

Consistently having a "type" in all messages going back and forth is
probably a good idea for the same reason as having cookies.

A final, remark unrelated to the protocol: Ideally the daemon should
delay writing into (and even creating!) the build directory for as
long as possible (or till instructed to actually persist the
configuration). We do have many users that use Qt Creator to browse
foreign code and those tend to get upset when we write stuff to disk.

Best Regards,
Tobias