summaryrefslogtreecommitdiffstats
path: root/Help/manual/cmake-server.7.rst
blob: 76ee3fb914551d2fd9b04166e5dd4005ebc58b78 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
.. cmake-manual-description: CMake Server

cmake-server(7)
***************

.. only:: html

   .. contents::

Introduction
============

:manual:`cmake(1)` is capable of providing semantic information about
CMake code it executes to generate a buildsystem.  If executed with
the ``-E server`` command line options, it starts in a long running mode
and allows a client to request the available information via a JSON protocol.

The protocol is designed to be useful to IDEs, refactoring tools, and
other tools which have a need to understand the buildsystem in entirety.

A single :manual:`cmake-buildsystem(7)` may describe buildsystem contents
and build properties which differ based on
:manual:`generation-time context <cmake-generator-expressions(7)>`
including:

* The Platform (eg, Windows, APPLE, Linux).
* The build configuration (eg, Debug, Release, Coverage).
* The Compiler (eg, MSVC, GCC, Clang) and compiler version.
* The language of the source files compiled.
* Available compile features (eg CXX variadic templates).
* CMake policies.

The protocol aims to provide information to tooling to satisfy several
needs:

#. Provide a complete and easily parsed source of all information relevant
   to the tooling as it relates to the source code.  There should be no need
   for tooling to parse generated buildsystems to access include directories
   or compile definitions for example.
#. Semantic information about the CMake buildsystem itself.
#. Provide a stable interface for reading the information in the CMake cache.
#. Information for determining when cmake needs to be re-run as a result of
   file changes.


Operation
=========

Start :manual:`cmake(1)` in the server command mode, supplying the path to
the build directory to process::

  cmake -E server (--debug|--pipe <NAMED_PIPE>)

The server will communicate using stdin/stdout (with the ``--debug`` parameter)
or using a named pipe (with the ``--pipe <NAMED_PIPE>`` parameter).

When connecting to the server (via named pipe or by starting it in ``--debug``
mode), the server will reply with a hello message::

  [== CMake Server ==[
  {"supportedProtocolVersions":[{"major":1,"minor":0}],"type":"hello"}
  ]== CMake Server ==]

Messages sent to and from the process are wrapped in magic strings::

  [== CMake Server ==[
  {
    ... some JSON message ...
  }
  ]== CMake Server ==]

The server is now ready to accept further requests via the named pipe
or 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
============


General Message Layout
----------------------

All messages need to have a "type" value, which identifies the type of
message that is passed back or forth. E.g. the initial message sent by the
server is of type "hello". Messages without a type will generate an response
of type "error".

All requests sent to the server may contain a "cookie" value. This value
will he handed back unchanged in all responses triggered by the request.

All responses will contain a value "inReplyTo", which may be empty in
case of parse errors, but will contain the type of the request message
in all other cases.


Type "reply"
^^^^^^^^^^^^

This type is used by the server to reply to requests.

The message may -- depending on the type of the original request --
contain values.

Example::

  [== CMake Server ==[
  {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
  ]== CMake Server ==]


Type "error"
^^^^^^^^^^^^

This type is used to return an error condition to the client. It will
contain an "errorMessage".

Example::

  [== CMake Server ==[
  {"cookie":"","errorMessage":"Protocol version not supported.","inReplyTo":"handshake","type":"error"}
  ]== CMake Server ==]


Type "progress"
^^^^^^^^^^^^^^^

When the server is busy for a long time, it is polite to send back replies of
type "progress" to the client. These will contain a "progressMessage" with a
string describing the action currently taking place as well as
"progressMinimum", "progressMaximum" and "progressCurrent" with integer values
describing the range of progess.

Messages of type "progress" will be followed by more "progress" messages or with
a message of type "reply" or "error" that complete the request.

"progress" messages may not be emitted after the "reply" or "error" message for
the request that triggered the responses was delivered.


Type "message"
^^^^^^^^^^^^^^

A message is triggered when the server processes a request and produces some
form of output that should be displayed to the user. A Message has a "message"
with the actual text to display as well as a "title" with a suggested dialog
box title.

Example::

  [== CMake Server ==[
  {"cookie":"","message":"Something happened.","title":"Title Text","inReplyTo":"handshake","type":"message"}
  ]== CMake Server ==]


Type "signal"
^^^^^^^^^^^^^

The server can send signals when it detects changes in the system state. Signals
are of type "signal", have an empty "cookie" and "inReplyTo" field and always
have a "name" set to show which signal was sent.


Specific Message Types
----------------------


Type "hello"
^^^^^^^^^^^^

The initial message send by the cmake server on startup is of type "hello".
This is the only message ever sent by the server that is not of type "reply",
"progress" or "error".

It will contain "supportedProtocolVersions" with an array of server protocol
versions supported by the cmake server. These are JSON objects with "major" and
"minor" keys containing non-negative integer values.

Example::

  [== CMake Server ==[
  {"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"}
  ]== CMake Server ==]


Type "handshake"
^^^^^^^^^^^^^^^^

The first request that the client may send to the server is of type "handshake".

This request needs to pass one of the "supportedProtocolVersions" of the "hello"
type response received earlier back to the server in the "protocolVersion" field.

Each protocol version may request additional attributes to be present.

Protocol version 1.0 requires the following attributes to be set:

  * "sourceDirectory" with a path to the sources
  * "buildDirectory" with a path to the build directory
  * "generator" with the generator name
  * "extraGenerator" (optional!) with the extra generator to be used.

Example::

  [== CMake Server ==[
  {"cookie":"zimtstern","type":"handshake","protocolVersion":{"major":0},
   "sourceDirectory":"/home/code/cmake", "buildDirectory":"/tmp/testbuild",
   "generator":"Ninja"}
  ]== CMake Server ==]

which will result in a response type "reply"::

  [== CMake Server ==[
  {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
  ]== CMake Server ==]

indicating that the server is ready for action.


Type "globalSettings"
^^^^^^^^^^^^^^^^^^^^^

This request can be sent after the initial handshake. It will return a
JSON structure with information on cmake state.

Example::

  [== CMake Server ==[
  {"type":"globalSettings"}
  ]== CMake Server ==]

which will result in a response type "reply"::

  [== CMake Server ==[
  {
    "buildDirectory": "/tmp/test-build",
    "capabilities": {
      "generators": [
        {
          "extraGenerators": [],
          "name": "Watcom WMake",
          "platformSupport": false,
          "toolsetSupport": false
        },
        <...>
      ],
      "serverMode": false,
      "version": {
        "isDirty": false,
        "major": 3,
        "minor": 6,
        "patch": 20160830,
        "string": "3.6.20160830-gd6abad",
        "suffix": "gd6abad"
      }
    },
    "checkSystemVars": false,
    "cookie": "",
    "extraGenerator": "",
    "generator": "Ninja",
    "debugOutput": false,
    "inReplyTo": "globalSettings",
    "sourceDirectory": "/home/code/cmake",
    "trace": false,
    "traceExpand": false,
    "type": "reply",
    "warnUninitialized": false,
    "warnUnused": false,
    "warnUnusedCli": true
  }
  ]== CMake Server ==]


Type "setGlobalSettings"
^^^^^^^^^^^^^^^^^^^^^^^^

This request can be sent to change the global settings attributes. Unknown
attributes are going to be ignored. Read-only attributes reported by
"globalSettings" are all capabilities, buildDirectory, generator,
extraGenerator and sourceDirectory. Any attempt to set these will be ignored,
too.

All other settings will be changed.

The server will respond with an empty reply message or an error.

Example::

  [== CMake Server ==[
  {"type":"setGlobalSettings","debugOutput":true}
  ]== CMake Server ==]

CMake will reply to this with::

  [== CMake Server ==[
  {"inReplyTo":"setGlobalSettings","type":"reply"}
  ]== CMake Server ==]


Type "configure"
^^^^^^^^^^^^^^^^

This request will configure a project for build.

To configure a build directory already containing cmake files, it is enough to
set "buildDirectory" via "setGlobalSettings". To create a fresh build directory
you also need to set "currentGenerator" and "sourceDirectory" via "setGlobalSettings"
in addition to "buildDirectory".

You may a list of strings to "configure" via the "cacheArguments" key. These
strings will be interpreted similar to command line arguments related to
cache handling that are passed to the cmake command line client.

Example::

  [== CMake Server ==[
  {"type":"configure", "cacheArguments":["-Dsomething=else"]}
  ]== CMake Server ==]

CMake will reply like this (after reporting progress for some time)::

  [== CMake Server ==[
  {"cookie":"","inReplyTo":"configure","type":"reply"}
  ]== CMake Server ==]


Type "compute"
^^^^^^^^^^^^^^

This requist will generate build system files in the build directory and
is only available after a project was successfully "configure"d.

Example::

  [== CMake Server ==[
  {"type":"compute"}
  ]== CMake Server ==]

CMake will reply (after reporting progress information)::

  [== CMake Server ==[
  {"cookie":"","inReplyTo":"compute","type":"reply"}
  ]== CMake Server ==]


Type "codemodel"
^^^^^^^^^^^^^^^^

The "codemodel" request can be used after a project was "compute"d successfully.

It will list the complete project structure as it is known to cmake.

The reply will contain a key "projects", which will contain a list of
project objects, one for each (sub-)project defined in the cmake build system.

Each project object can have the following keys:

"name"
  contains the (sub-)projects name.
"sourceDirectory"
  contains the current source directory
"buildDirectory"
  contains the current build directory.
"configurations"
  contains a list of configuration objects.

Configuration objects are used to destinquish between different
configurations the build directory might have enabled. While most generators
only support one configuration, others support several.

Each configuration object can have the following keys:

"name"
  contains the name of the configuration. The name may be empty.
"targets"
  contains a list of target objects, one for each build target.

Target objects define individual build targets for a certain configuration.

Each target object can have the following keys:

"name"
  contains the name of the target.
"type"
  defines the type of build of the target. Possible values are
  "STATIC_LIBRARY", "MODULE_LIBRARY", "SHARED_LIBRARY", "OBJECT_LIBRARY",
  "EXECUTABLE", "UTILITY" and "INTERFACE_LIBRARY".
"fullName"
  contains the full name of the build result (incl. extensions, etc.).
"sourceDirectory"
  contains the current source directory.
"buildDirectory"
  contains the current build directory.
"artifacts"
  with a list of build artifacts. The list is sorted with the most
  important artifacts first (e.g. a .DLL file is listed before a
  .PDB file on windows).
"linkerLanguage"
  contains the language of the linker used to produce the artifact.
"linkLibraries"
  with a list of libraries to link to. This value is encoded in the
  system's native shell format.
"linkFlags"
  with a list of flags to pass to the linker. This value is encoded in
  the system's native shell format.
"linkLanguageFlags"
  with the flags for a compiler using the linkerLanguage. This value is
  encoded in the system's native shell format.
"frameworkPath"
  with the framework path (on Apple computers). This value is encoded
  in the system's native shell format.
"linkPath"
  with the link path. This value is encoded in the system's native shell
  format.
"sysroot"
  with the sysroot path.
"fileGroups"
  contains the source files making up the target.

FileGroups are used to group sources using similar settings together.

Each fileGroup object may contain the following keys:

"language"
  contains the programming language used by all files in the group.
"compileFlags"
  with a string containing all the flags passed to the compiler
  when building any of the files in this group. This value is encoded in
  the system's native shell format.
"includePath"
  with a list of include paths. Each include path is an object
  containing a "path" with the actual include path and "isSystem" with a bool
  value informing whether this is a normal include or a system include. This
  value is encoded in the system's native shell format.
"defines"
  with a list of defines in the form "SOMEVALUE" or "SOMEVALUE=42". This
  value is encoded in the system's native shell format.
"sources"
  with a list of source files.

All file paths in the fileGroup are either absolute or relative to the
sourceDirectory of the target.

Example::

  [== CMake Server ==[
  {"type":"project"}
  ]== CMake Server ==]

CMake will reply::

  [== CMake Server ==[
  {
    "cookie":"",
    "type":"reply",
    "inReplyTo":"project",

    "projects":
    [
      {
        "name":"CMAKE_FORM",
        "sourceDirectory":"/home/code/src/cmake/Source/CursesDialog/form"
        "buildDirectory":"/tmp/cmake-build-test/Source/CursesDialog/form",
        "configurations":
        [
          {
            "name":"",
            "targets":
            [
              {
                "artifactDirectory":"/tmp/cmake/Source/CursesDialog/form",
                "fileGroups":
                [
                  {
                    "compileFlags":"  -std=gnu11",
                    "defines":
                    [
                      "SOMETHING=1",
                      "LIBARCHIVE_STATIC"
                    ],
                    "includePath":
                    [
                      { "path":"/tmp/cmake-build-test/Utilities" },
                      { "isSystem": true, "path":"/usr/include/something" },
                      ...
                    ]
                    "language":"C",
                    "sources":
                    [
                      "fld_arg.c",
                      ...
                      "fty_regex.c"
                    ]
                  }
                ],
                "fullName":"libcmForm.a",
                "linkerLanguage":"C",
                "name":"cmForm",
                "type":"STATIC_LIBRARY"
              }
            ]
          }
        ],
      },
      ...
    ]
  }
  ]== CMake Server ==]

The output can be tailored to the specific needs via parameter passed when
requesting "project" information.

You can have a "depth" key, which accepts "project", "configuration" and
"target" as string values. These cause the output to be trimmed at the
appropriate depth of the output tree.

You can also set "configurations" to an array of strings with configuration
names to list. This will cause any configuration that is not listed to be
trimmed from the output.

Generated files can be included in the listing by setting "includeGeneratedFiles"
to "true". This setting defaults to "false", so generated files are not
listed by default.

Finally you can limit the target types that are going to be listed. This is
done by providing a list of target types as an array of strings to the
"targetTypes" key.


Type "cmakeInputs"
^^^^^^^^^^^^^^^^^^

The "cmakeInputs" requests will report files used by CMake as part
of the build system itself.

This request is only available after a project was successfully
"configure"d.

Example::

  [== CMake Server ==[
  {"type":"cmakeInputs"}
  ]== CMake Server ==]

CMake will reply with the following information::

  [== CMake Server ==[
  {"buildFiles":
    [
      {"isCMake":true,"isTemporary":false,"sources":["/usr/lib/cmake/...", ... ]},
      {"isCMake":false,"isTemporary":false,"sources":["CMakeLists.txt", ...]},
      {"isCMake":false,"isTemporary":true,"sources":["/tmp/build/CMakeFiles/...", ...]}
    ],
    "cmakeRootDirectory":"/usr/lib/cmake",
    "sourceDirectory":"/home/code/src/cmake",
    "cookie":"",
    "inReplyTo":"cmakeInputs",
    "type":"reply"
  }
  ]== CMake Server ==]

All file names are either relative to the top level source directory or
absolute.

The list of files which "isCMake" set to true are part of the cmake installation.

The list of files witch "isTemporary" set to true are part of the build directory
and will not survive the build directory getting cleaned out.