1CMAKE-SERVER(7) CMake CMAKE-SERVER(7)
2
3
4
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
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
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
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
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-2019 Kitware, Inc. and Contributors
739
740
741
742
7433.16.1 Dec 14, 2019 CMAKE-SERVER(7)