1CMAKE-SERVER(7)                      CMake                     CMAKE-SERVER(7)
2
3
4

NAME

6       cmake-server - CMake Server
7
8       Deprecated  since version 3.15: This will be removed from a future ver‐
9       sion of CMake.  Clients should use the cmake-file-api(7) instead.
10
11

INTRODUCTION

13       cmake(1) is capable of providing semantic information about CMake  code
14       it  executes to generate a buildsystem.  If executed with the -E server
15       command line options, it starts in a long running  mode  and  allows  a
16       client to request the available information via a JSON protocol.
17
18       The  protocol  is designed to be useful to IDEs, refactoring tools, and
19       other tools  which  have  a  need  to  understand  the  buildsystem  in
20       entirety.
21
22       A  single  cmake-buildsystem(7)  may  describe buildsystem contents and
23       build properties which differ based on generation-time context  includ‐
24       ing:
25
26       · The Platform (eg, Windows, APPLE, Linux).
27
28       · The build configuration (eg, Debug, Release, Coverage).
29
30       · The Compiler (eg, MSVC, GCC, Clang) and compiler version.
31
32       · The language of the source files compiled.
33
34       · Available compile features (eg CXX variadic templates).
35
36       · CMake policies.
37
38       The  protocol aims to provide information to tooling to satisfy several
39       needs:
40
41       1. Provide a complete and easily parsed source of all information rele‐
42          vant  to the tooling as it relates to the source code.  There should
43          be no need for tooling to parse  generated  buildsystems  to  access
44          include directories or compile definitions for example.
45
46       2. Semantic information about the CMake buildsystem itself.
47
48       3. Provide  a stable interface for reading the information in the CMake
49          cache.
50
51       4. Information for determining when cmake  needs  to  be  re-run  as  a
52          result of file changes.
53

OPERATION

55       Start  cmake(1)  in  the server command mode, supplying the path to the
56       build directory to process:
57
58          cmake -E server (--debug|--pipe=<NAMED_PIPE>)
59
60       The server will communicate using stdin/stdout (with the --debug param‐
61       eter)  or  using a named pipe (with the --pipe=<NAMED_PIPE> parameter).
62       Note that “named pipe” refers to a local domain socket on Unix and to a
63       named pipe on Windows.
64
65       When  connecting  to  the  server  (via named pipe or by starting it in
66       --debug mode), the server will reply with a hello message:
67
68          [== "CMake Server" ==[
69          {"supportedProtocolVersions":[{"major":1,"minor":0}],"type":"hello"}
70          ]== "CMake Server" ==]
71
72       Messages sent to and from the process are wrapped in magic strings:
73
74          [== "CMake Server" ==[
75          {
76            ... some JSON message ...
77          }
78          ]== "CMake Server" ==]
79
80       The server is now ready to accept further requests via the  named  pipe
81       or stdin.
82

DEBUGGING

84       CMake  server  mode  can  be  asked  to provide statistics on execution
85       times, etc.  or to dump a copy of the response into  a  file.  This  is
86       done passing a “debug” JSON object as a child of the request.
87
88       The  debug  object  supports the “showStats” key, which takes a boolean
89       and makes the server mode return a “zzzDebug” object with stats as part
90       of  its response.  “dumpToFile” takes a string value and will cause the
91       cmake server to copy the response into the given filename.
92
93       This is a response from the cmake server with “showStats” set to true:
94
95          [== "CMake Server" ==[
96          {
97            "cookie":"",
98            "errorMessage":"Waiting for type \"handshake\".",
99            "inReplyTo":"unknown",
100           "type":"error",
101            "zzzDebug": {
102              "dumpFile":"/tmp/error.txt",
103              "jsonSerialization":0.011016,
104              "size":111,
105              "totalTime":0.025995
106            }
107          }
108          ]== "CMake Server" ==]
109
110       The  server  has  made  a  copy  of  this  response   into   the   file
111       /tmp/error.txt  and took 0.011 seconds to turn the JSON response into a
112       string, and it took 0.025 seconds to process the request in total.  The
113       reply has a size of 111 bytes.
114

PROTOCOL API

116   General Message Layout
117       All  messages need to have a “type” value, which identifies the type of
118       message that is passed back or forth. E.g. the initial message sent  by
119       the server is of type “hello”. Messages without a type will generate an
120       response of type “error”.
121
122       All requests sent to the server may  contain  a  “cookie”  value.  This
123       value  will  he handed back unchanged in all responses triggered by the
124       request.
125
126       All responses will contain a value “inReplyTo”, which may be  empty  in
127       case  of parse errors, but will contain the type of the request message
128       in all other cases.
129
130   Type “reply”
131       This type is used by the server to reply to requests.
132
133       The message may – depending on the type of the original request –  con‐
134       tain values.
135
136       Example:
137
138          [== "CMake Server" ==[
139          {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
140          ]== "CMake Server" ==]
141
142   Type “error”
143       This  type  is used to return an error condition to the client. It will
144       contain an “errorMessage”.
145
146       Example:
147
148          [== "CMake Server" ==[
149          {"cookie":"","errorMessage":"Protocol version not supported.","inReplyTo":"handshake","type":"error"}
150          ]== "CMake Server" ==]
151
152   Type “progress”
153       When the server is busy for a long time, it  is  polite  to  send  back
154       replies  of  type  “progress” to the client. These will contain a “pro‐
155       gressMessage” with a string  describing  the  action  currently  taking
156       place as well as “progressMinimum”, “progressMaximum” and “progressCur‐
157       rent” with integer values describing the range of progress.
158
159       Messages of type “progress” will be followed by  more  “progress”  mes‐
160       sages  or  with  a message of type “reply” or “error” that complete the
161       request.
162
163       “progress” messages may not be emitted after  the  “reply”  or  “error”
164       message for the request that triggered the responses was delivered.
165
166   Type “message”
167       A message is triggered when the server processes a request and produces
168       some form of output that should be displayed to the user. A Message has
169       a “message” with the actual text to display as well as a “title” with a
170       suggested dialog box title.
171
172       Example:
173
174          [== "CMake Server" ==[
175          {"cookie":"","message":"Something happened.","title":"Title Text","inReplyTo":"handshake","type":"message"}
176          ]== "CMake Server" ==]
177
178   Type “signal”
179       The server can send signals when  it  detects  changes  in  the  system
180       state.  Signals are of type “signal”, have an empty “cookie” and “inRe‐
181       plyTo” field and always have a “name” set  to  show  which  signal  was
182       sent.
183
184   Specific Signals
185       The cmake server may sent signals with the following names:
186
187   “dirty” Signal
188       The “dirty” signal is sent whenever the server determines that the con‐
189       figuration of the project is no longer up-to-date.  This  happens  when
190       any of the files that have an influence on the build system is changed.
191
192       The “dirty” signal may look like this:
193
194          [== "CMake Server" ==[
195          {
196            "cookie":"",
197            "inReplyTo":"",
198            "name":"dirty",
199            "type":"signal"}
200          ]== "CMake Server" ==]
201
202   “fileChange” Signal
203       The  “fileChange” signal is sent whenever a watched file is changed. It
204       contains the “path” that has changed and a list  of  “properties”  with
205       the kind of change that was detected. Possible changes are “change” and
206       “rename”.
207
208       The “fileChange” signal looks like this:
209
210          [== "CMake Server" ==[
211          {
212            "cookie":"",
213            "inReplyTo":"",
214            "name":"fileChange",
215            "path":"/absolute/CMakeLists.txt",
216            "properties":["change"],
217            "type":"signal"}
218          ]== "CMake Server" ==]
219
220   Specific Message Types
221   Type “hello”
222       The initial message send by the cmake server  on  startup  is  of  type
223       “hello”.   This is the only message ever sent by the server that is not
224       of type “reply”, “progress” or “error”.
225
226       It will contain “supportedProtocolVersions” with  an  array  of  server
227       protocol versions supported by the cmake server. These are JSON objects
228       with “major” and “minor” keys containing non-negative  integer  values.
229       Some  versions  may  be  marked as experimental. These will contain the
230       “isExperimental” key set to true. Enabling  these  requires  a  special
231       command line argument when starting the cmake server mode.
232
233       Within  a “major” version all “minor” versions are fully backwards com‐
234       patible.  New “minor” versions may introduce functionality  in  such  a
235       way  that existing clients of the same “major” version will continue to
236       work, provided they ignore keys in the output that  they  do  not  know
237       about.
238
239       Example:
240
241          [== "CMake Server" ==[
242          {"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"}
243          ]== "CMake Server" ==]
244
245   Type “handshake”
246       The  first  request  that  the client may send to the server is of type
247       “handshake”.
248
249       This request needs to pass one of  the  “supportedProtocolVersions”  of
250       the  “hello”  type  response received earlier back to the server in the
251       “protocolVersion” field.  Giving the “major” version of  the  requested
252       protocol  version  will make the server use the latest minor version of
253       that protocol. Use this if you do not explicitly need to  depend  on  a
254       specific minor version.
255
256       Protocol version 1.0 requires the following attributes to be set:
257
258          · “sourceDirectory” with a path to the sources
259
260          · “buildDirectory” with a path to the build directory
261
262          · “generator” with the generator name
263
264          · “extraGenerator” (optional!) with the extra generator to be used
265
266          · “platform” with the generator platform (if supported by the gener‐
267            ator)
268
269          · “toolset” with the generator toolset (if supported by the  genera‐
270            tor)
271
272       Protocol  version  1.2 makes all but the build directory optional, pro‐
273       vided there is a valid cache in the build directory that  contains  all
274       the other information already.
275
276       Example:
277
278          [== "CMake Server" ==[
279          {"cookie":"zimtstern","type":"handshake","protocolVersion":{"major":0},
280           "sourceDirectory":"/home/code/cmake", "buildDirectory":"/tmp/testbuild",
281           "generator":"Ninja"}
282          ]== "CMake Server" ==]
283
284       which will result in a response type “reply”:
285
286          [== "CMake Server" ==[
287          {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
288          ]== "CMake Server" ==]
289
290       indicating that the server is ready for action.
291
292   Type “globalSettings”
293       This  request can be sent after the initial handshake. It will return a
294       JSON structure with information on cmake state.
295
296       Example:
297
298          [== "CMake Server" ==[
299          {"type":"globalSettings"}
300          ]== "CMake Server" ==]
301
302       which will result in a response type “reply”:
303
304          [== "CMake Server" ==[
305          {
306            "buildDirectory": "/tmp/test-build",
307            "capabilities": {
308              "generators": [
309                {
310                  "extraGenerators": [],
311                  "name": "Watcom WMake",
312                  "platformSupport": false,
313                  "toolsetSupport": false
314                },
315                <...>
316              ],
317              "serverMode": false,
318              "version": {
319                "isDirty": false,
320                "major": 3,
321                "minor": 6,
322                "patch": 20160830,
323                "string": "3.6.20160830-gd6abad",
324                "suffix": "gd6abad"
325              }
326            },
327            "checkSystemVars": false,
328            "cookie": "",
329            "extraGenerator": "",
330            "generator": "Ninja",
331            "debugOutput": false,
332            "inReplyTo": "globalSettings",
333            "sourceDirectory": "/home/code/cmake",
334            "trace": false,
335            "traceExpand": false,
336            "type": "reply",
337            "warnUninitialized": false,
338            "warnUnused": false,
339            "warnUnusedCli": true
340          }
341          ]== "CMake Server" ==]
342
343   Type “setGlobalSettings”
344       This request can be sent to  change  the  global  settings  attributes.
345       Unknown  attributes  are  going  to  be  ignored.  Read-only attributes
346       reported by “globalSettings” are all capabilities, buildDirectory, gen‐
347       erator,  extraGenerator  and  sourceDirectory. Any attempt to set these
348       will be ignored, too.
349
350       All other settings will be changed.
351
352       The server will respond with an empty reply message or an error.
353
354       Example:
355
356          [== "CMake Server" ==[
357          {"type":"setGlobalSettings","debugOutput":true}
358          ]== "CMake Server" ==]
359
360       CMake will reply to this with:
361
362          [== "CMake Server" ==[
363          {"inReplyTo":"setGlobalSettings","type":"reply"}
364          ]== "CMake Server" ==]
365
366   Type “configure”
367       This request will configure a project for build.
368
369       To configure a build directory already containing cmake  files,  it  is
370       enough  to  set  “buildDirectory”  via “setGlobalSettings”. To create a
371       fresh build directory you  also  need  to  set  “currentGenerator”  and
372       “sourceDirectory”  via  “setGlobalSettings” in addition to “buildDirec‐
373       tory”.
374
375       You may a list of strings to “configure” via the “cacheArguments”  key.
376       These  strings  will  be  interpreted similar to command line arguments
377       related to cache handling that are passed to  the  cmake  command  line
378       client.
379
380       Example:
381
382          [== "CMake Server" ==[
383          {"type":"configure", "cacheArguments":["-Dsomething=else"]}
384          ]== "CMake Server" ==]
385
386       CMake will reply like this (after reporting progress for some time):
387
388          [== "CMake Server" ==[
389          {"cookie":"","inReplyTo":"configure","type":"reply"}
390          ]== "CMake Server" ==]
391
392   Type “compute”
393       This  request  will  generate build system files in the build directory
394       and is only available after a project was successfully “configure”d.
395
396       Example:
397
398          [== "CMake Server" ==[
399          {"type":"compute"}
400          ]== "CMake Server" ==]
401
402       CMake will reply (after reporting progress information):
403
404          [== "CMake Server" ==[
405          {"cookie":"","inReplyTo":"compute","type":"reply"}
406          ]== "CMake Server" ==]
407
408   Type “codemodel”
409       The “codemodel” request can be used after a project was “compute”d suc‐
410       cessfully.
411
412       It will list the complete project structure as it is known to cmake.
413
414       The  reply  will  contain  a key “configurations”, which will contain a
415       list of configuration objects. Configuration objects are used  to  des‐
416       tinquish  between  different  configurations  the build directory might
417       have enabled. While most generators  only  support  one  configuration,
418       others might support several.
419
420       Each configuration object can have the following keys:
421
422       “name” contains the name of the configuration. The name may be empty.
423
424       “projects”
425              contains a list of project objects, one for each build project.
426
427       Project  objects  define  one  (sub-)project defined in the cmake build
428       system.
429
430       Each project object can have the following keys:
431
432       “name” contains the (sub-)projects name.
433
434       “minimumCMakeVersion”
435              contains the minimum cmake version  allowed  for  this  project,
436              null if the project doesn’t specify one.
437
438       “hasInstallRule”
439              true if the project contains any install rules, false otherwise.
440
441       “sourceDirectory”
442              contains the current source directory
443
444       “buildDirectory”
445              contains the current build directory.
446
447       “targets”
448              contains a list of build system target objects.
449
450       Target objects define individual build targets for a certain configura‐
451       tion.
452
453       Each target object can have the following keys:
454
455       “name” contains the name of the target.
456
457       “type” defines the type of build of the  target.  Possible  values  are
458              “STATIC_LIBRARY”,       “MODULE_LIBRARY”,      “SHARED_LIBRARY”,
459              “OBJECT_LIBRARY”,   “EXECUTABLE”,    “UTILITY”    and    “INTER‐
460              FACE_LIBRARY”.
461
462       “fullName”
463              contains  the  full  name of the build result (incl. extensions,
464              etc.).
465
466       “sourceDirectory”
467              contains the current source directory.
468
469       “buildDirectory”
470              contains the current build directory.
471
472       “isGeneratorProvided”
473              true if the target is auto-created by a generator, false  other‐
474              wise
475
476       “hasInstallRule”
477              true if the target contains any install rules, false otherwise.
478
479       “installPaths”
480              full  path  to  the  destination  directories  defined by target
481              install rules.
482
483       “artifacts”
484              with a list of build artifacts. The list is sorted with the most
485              important artifacts first (e.g. a .DLL file is listed before a
486
487       “linkerLanguage”
488              contains  the  language  of the linker used to produce the arti‐
489              fact.
490
491       “linkLibraries”
492              with a list of libraries to link to. This value  is  encoded  in
493              the system’s native shell format.
494
495       “linkFlags”
496              with  a  list  of  flags  to  pass  to the linker. This value is
497              encoded in the system’s native shell format.
498
499       “linkLanguageFlags”
500              with the flags for a compiler  using  the  linkerLanguage.  This
501              value is encoded in the system’s native shell format.
502
503       “frameworkPath”
504              with  the  framework  path  (on  Apple computers). This value is
505              encoded in the system’s native shell format.
506
507       “linkPath”
508              with the link path. This value is encoded in the system’s native
509              shell format.
510
511       “sysroot”
512              with the sysroot path.
513
514       “fileGroups”
515              contains the source files making up the target.
516
517       FileGroups are used to group sources using similar settings together.
518
519       Each fileGroup object may contain the following keys:
520
521       “language”
522              contains  the  programming  language  used  by  all files in the
523              group.
524
525       “compileFlags”
526              with a string containing all the flags passed  to  the  compiler
527              when  building  any  of  the  files in this group. This value is
528              encoded in the system’s native shell format.
529
530       “includePath”
531              with a list of include paths. Each include  path  is  an  object
532              containing  a “path” with the actual include path and “isSystem”
533              with a bool value informing whether this is a normal include  or
534              a  system  include. This value is encoded in the system’s native
535              shell format.
536
537       “defines”
538              with  a  list  of   defines   in   the   form   “SOMEVALUE”   or
539              “SOMEVALUE=42”.  This  value  is  encoded in the system’s native
540              shell format.
541
542       “sources”
543              with a list of source files.
544
545       All file paths in the fileGroup are either absolute or relative to  the
546       sourceDirectory of the target.
547
548       Example:
549
550          [== "CMake Server" ==[
551          {"type":"codemodel"}
552          ]== "CMake Server" ==]
553
554       CMake will reply:
555
556          [== "CMake Server" ==[
557          {
558            "configurations": [
559              {
560                "name": "",
561                "projects": [
562                  {
563                    "buildDirectory": "/tmp/build/Source/CursesDialog/form",
564                    "name": "CMAKE_FORM",
565                    "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
566                    "targets": [
567                      {
568                        "artifacts": [ "/tmp/build/Source/CursesDialog/form/libcmForm.a" ],
569                        "buildDirectory": "/tmp/build/Source/CursesDialog/form",
570                        "fileGroups": [
571                          {
572                            "compileFlags": "  -std=gnu11",
573                            "defines": [ "CURL_STATICLIB", "LIBARCHIVE_STATIC" ],
574                            "includePath": [ { "path": "/tmp/build/Utilities" }, <...> ],
575                            "isGenerated": false,
576                            "language": "C",
577                            "sources": [ "fld_arg.c", <...> ]
578                          }
579                        ],
580                        "fullName": "libcmForm.a",
581                        "linkerLanguage": "C",
582                        "name": "cmForm",
583                        "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
584                        "type": "STATIC_LIBRARY"
585                      }
586                    ]
587                  },
588                  <...>
589                ]
590              }
591            ],
592            "cookie": "",
593            "inReplyTo": "codemodel",
594            "type": "reply"
595          }
596          ]== "CMake Server" ==]
597
598   Type “ctestInfo”
599       The “ctestInfo” request can be used after a project was “compute”d suc‐
600       cessfully.
601
602       It will list the complete project test structure  as  it  is  known  to
603       cmake.
604
605       The  reply  will  contain  a key “configurations”, which will contain a
606       list of configuration objects. Configuration objects are used  to  des‐
607       tinquish  between  different  configurations  the build directory might
608       have enabled. While most generators  only  support  one  configuration,
609       others might support several.
610
611       Each configuration object can have the following keys:
612
613       “name” contains the name of the configuration. The name may be empty.
614
615       “projects”
616              contains a list of project objects, one for each build project.
617
618       Project  objects  define  one  (sub-)project defined in the cmake build
619       system.
620
621       Each project object can have the following keys:
622
623       “name” contains the (sub-)projects name.
624
625       “ctestInfo”
626              contains a list of test objects.
627
628       Each test object can have the following keys:
629
630       “ctestName”
631              contains the name of the test.
632
633       “ctestCommand”
634              contains the test command.
635
636       “properties”
637              contains a list of test property objects.
638
639       Each test property object can have the following keys:
640
641       “key”  contains the test property key.
642
643       “value”
644              contains the test property value.
645
646   Type “cmakeInputs”
647       The “cmakeInputs” requests will report files used by CMake as  part  of
648       the build system itself.
649
650       This  request  is only available after a project was successfully “con‐
651       figure”d.
652
653       Example:
654
655          [== "CMake Server" ==[
656          {"type":"cmakeInputs"}
657          ]== "CMake Server" ==]
658
659       CMake will reply with the following information:
660
661          [== "CMake Server" ==[
662          {"buildFiles":
663            [
664              {"isCMake":true,"isTemporary":false,"sources":["/usr/lib/cmake/...", ... ]},
665              {"isCMake":false,"isTemporary":false,"sources":["CMakeLists.txt", ...]},
666              {"isCMake":false,"isTemporary":true,"sources":["/tmp/build/CMakeFiles/...", ...]}
667            ],
668            "cmakeRootDirectory":"/usr/lib/cmake",
669            "sourceDirectory":"/home/code/src/cmake",
670            "cookie":"",
671            "inReplyTo":"cmakeInputs",
672            "type":"reply"
673          }
674          ]== "CMake Server" ==]
675
676       All file names are either relative to the top level source directory or
677       absolute.
678
679       The  list  of  files  which “isCMake” set to true are part of the cmake
680       installation.
681
682       The list of files witch “isTemporary” set to true are part of the build
683       directory and will not survive the build directory getting cleaned out.
684
685   Type “cache”
686       The “cache” request will list the cached configuration values.
687
688       Example:
689
690          [== "CMake Server" ==[
691          {"type":"cache"}
692          ]== "CMake Server" ==]
693
694       CMake will respond with the following output:
695
696          [== "CMake Server" ==[
697          {
698            "cookie":"","inReplyTo":"cache","type":"reply",
699            "cache":
700            [
701              {
702                "key":"SOMEVALUE",
703                "properties":
704                {
705                  "ADVANCED":"1",
706                  "HELPSTRING":"This is not helpful"
707                }
708                "type":"STRING",
709                "value":"TEST"}
710            ]
711          }
712          ]== "CMake Server" ==]
713
714       The  output can be limited to a list of keys by passing an array of key
715       names to the “keys” optional field of the “cache” request.
716
717   Type “fileSystemWatchers”
718       The server can watch the filesystem for changes. The  “fileSystemWatch‐
719       ers” command will report on the files and directories watched.
720
721       Example:
722
723          [== "CMake Server" ==[
724          {"type":"fileSystemWatchers"}
725          ]== "CMake Server" ==]
726
727       CMake will respond with the following output:
728
729          [== "CMake Server" ==[
730          {
731            "cookie":"","inReplyTo":"fileSystemWatchers","type":"reply",
732            "watchedFiles": [ "/absolute/path" ],
733            "watchedDirectories": [ "/absolute" ]
734          }
735          ]== "CMake Server" ==]
736
738       2000-2020 Kitware, Inc. and Contributors
739
740
741
742
7433.17.2                           Apr 28, 2020                  CMAKE-SERVER(7)
Impressum