1CMAKE-SERVER(7) CMake CMAKE-SERVER(7)
2
6 cmake-server - CMake Server
7 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
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 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 A single cmake-buildsystem(7) may describe buildsystem contents and
23 build properties which differ based on generation-time context includ‐
24 ing:
25 · The Platform (eg, Windows, APPLE, Linux).
27 · The build configuration (eg, Debug, Release, Coverage).
29 · The Compiler (eg, MSVC, GCC, Clang) and compiler version.
31 · The language of the source files compiled.
33 · Available compile features (eg CXX variadic templates).
35 · CMake policies.
37 The protocol aims to provide information to tooling to satisfy several
39 needs:
40 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 2. Semantic information about the CMake buildsystem itself.
47 3. Provide a stable interface for reading the information in the CMake
49 cache.
50 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 cmake -E server (--debug|--pipe=<NAMED_PIPE>)
59 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 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 [== "CMake Server" ==[
69 {"supportedProtocolVersions":[{"major":1,"minor":0}],"type":"hello"}
70 ]== "CMake Server" ==]
71 Messages sent to and from the process are wrapped in magic strings:
73 [== "CMake Server" ==[
75 {
76 ... some JSON message ...
77 }
78 ]== "CMake Server" ==]
79 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 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 This is a response from the cmake server with “showStats” set to true:
94 [== "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 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 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 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 Type “reply”
131 This type is used by the server to reply to requests.
132 The message may – depending on the type of the original request – con‐
134 tain values.
135 Example:
137 [== "CMake Server" ==[
139 {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
140 ]== "CMake Server" ==]
141 Type “error”
143 This type is used to return an error condition to the client. It will
144 contain an “errorMessage”.
145 Example:
147 [== "CMake Server" ==[
149 {"cookie":"","errorMessage":"Protocol version not supported.","inReplyTo":"handshake","type":"error"}
150 ]== "CMake Server" ==]
151 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 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 “progress” messages may not be emitted after the “reply” or “error”
164 message for the request that triggered the responses was delivered.
165 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 Example:
173 [== "CMake Server" ==[
175 {"cookie":"","message":"Something happened.","title":"Title Text","inReplyTo":"handshake","type":"message"}
176 ]== "CMake Server" ==]
177 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 Specific Signals
185 The cmake server may sent signals with the following names:
186 “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 The “dirty” signal may look like this:
193 [== "CMake Server" ==[
195 {
196 "cookie":"",
197 "inReplyTo":"",
198 "name":"dirty",
199 "type":"signal"}
200 ]== "CMake Server" ==]
201 “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 The “fileChange” signal looks like this:
209 [== "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 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 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 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 Example:
240 [== "CMake Server" ==[
242 {"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"}
243 ]== "CMake Server" ==]
244 Type “handshake”
246 The first request that the client may send to the server is of type
247 “handshake”.
248 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 Protocol version 1.0 requires the following attributes to be set:
257 · “sourceDirectory” with a path to the sources
259 · “buildDirectory” with a path to the build directory
261 · “generator” with the generator name
263 · “extraGenerator” (optional!) with the extra generator to be used
265 · “platform” with the generator platform (if supported by the gener‐
267 ator)
268 · “toolset” with the generator toolset (if supported by the genera‐
270 tor)
271 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 Example:
277 [== "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 which will result in a response type “reply”:
285 [== "CMake Server" ==[
287 {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
288 ]== "CMake Server" ==]
289 indicating that the server is ready for action.
291 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 Example:
297 [== "CMake Server" ==[
299 {"type":"globalSettings"}
300 ]== "CMake Server" ==]
301 which will result in a response type “reply”:
303 [== "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 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 All other settings will be changed.
351 The server will respond with an empty reply message or an error.
353 Example:
355 [== "CMake Server" ==[
357 {"type":"setGlobalSettings","debugOutput":true}
358 ]== "CMake Server" ==]
359 CMake will reply to this with:
361 [== "CMake Server" ==[
363 {"inReplyTo":"setGlobalSettings","type":"reply"}
364 ]== "CMake Server" ==]
365 Type “configure”
367 This request will configure a project for build.
368 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 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 Example:
381 [== "CMake Server" ==[
383 {"type":"configure", "cacheArguments":["-Dsomething=else"]}
384 ]== "CMake Server" ==]
385 CMake will reply like this (after reporting progress for some time):
387 [== "CMake Server" ==[
389 {"cookie":"","inReplyTo":"configure","type":"reply"}
390 ]== "CMake Server" ==]
391 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 Example:
397 [== "CMake Server" ==[
399 {"type":"compute"}
400 ]== "CMake Server" ==]
401 CMake will reply (after reporting progress information):
403 [== "CMake Server" ==[
405 {"cookie":"","inReplyTo":"compute","type":"reply"}
406 ]== "CMake Server" ==]
407 Type “codemodel”
409 The “codemodel” request can be used after a project was “compute”d suc‐
410 cessfully.
411 It will list the complete project structure as it is known to cmake.
413 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 Each configuration object can have the following keys:
421 “name” contains the name of the configuration. The name may be empty.
423 “projects”
425 contains a list of project objects, one for each build project.
426 Project objects define one (sub-)project defined in the cmake build
428 system.
429 Each project object can have the following keys:
431 “name” contains the (sub-)projects name.
433 “minimumCMakeVersion”
435 contains the minimum cmake version allowed for this project,
436 null if the project doesn’t specify one.
437 “hasInstallRule”
439 true if the project contains any install rules, false otherwise.
440 “sourceDirectory”
442 contains the current source directory
443 “buildDirectory”
445 contains the current build directory.
446 “targets”
448 contains a list of build system target objects.
449 Target objects define individual build targets for a certain configura‐
451 tion.
452 Each target object can have the following keys:
454 “name” contains the name of the target.
456 “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 “fullName”
463 contains the full name of the build result (incl. extensions,
464 etc.).
465 “sourceDirectory”
467 contains the current source directory.
468 “buildDirectory”
470 contains the current build directory.
471 “isGeneratorProvided”
473 true if the target is auto-created by a generator, false other‐
474 wise
475 “hasInstallRule”
477 true if the target contains any install rules, false otherwise.
478 “installPaths”
480 full path to the destination directories defined by target
481 install rules.
482 “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 .PDB file on windows).
487 “linkerLanguage”
489 contains the language of the linker used to produce the arti‐
490 fact.
491 “linkLibraries”
493 with a list of libraries to link to. This value is encoded in
494 the system’s native shell format.
495 “linkFlags”
497 with a list of flags to pass to the linker. This value is
498 encoded in the system’s native shell format.
499 “linkLanguageFlags”
501 with the flags for a compiler using the linkerLanguage. This
502 value is encoded in the system’s native shell format.
503 “frameworkPath”
505 with the framework path (on Apple computers). This value is
506 encoded in the system’s native shell format.
507 “linkPath”
509 with the link path. This value is encoded in the system’s native
510 shell format.
511 “sysroot”
513 with the sysroot path.
514 “fileGroups”
516 contains the source files making up the target.
517 FileGroups are used to group sources using similar settings together.
519 Each fileGroup object may contain the following keys:
521 “language”
523 contains the programming language used by all files in the
524 group.
525 “compileFlags”
527 with a string containing all the flags passed to the compiler
528 when building any of the files in this group. This value is
529 encoded in the system’s native shell format.
530 “includePath”
532 with a list of include paths. Each include path is an object
533 containing a “path” with the actual include path and “isSystem”
534 with a bool value informing whether this is a normal include or
535 a system include. This value is encoded in the system’s native
536 shell format.
537 “defines”
539 with a list of defines in the form “SOMEVALUE” or
540 “SOMEVALUE=42”. This value is encoded in the system’s native
541 shell format.
542 “sources”
544 with a list of source files.
545 All file paths in the fileGroup are either absolute or relative to the
547 sourceDirectory of the target.
548 Example:
550 [== "CMake Server" ==[
552 {"type":"codemodel"}
553 ]== "CMake Server" ==]
554 CMake will reply:
556 [== "CMake Server" ==[
558 {
559 "configurations": [
560 {
561 "name": "",
562 "projects": [
563 {
564 "buildDirectory": "/tmp/build/Source/CursesDialog/form",
565 "name": "CMAKE_FORM",
566 "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
567 "targets": [
568 {
569 "artifacts": [ "/tmp/build/Source/CursesDialog/form/libcmForm.a" ],
570 "buildDirectory": "/tmp/build/Source/CursesDialog/form",
571 "fileGroups": [
572 {
573 "compileFlags": " -std=gnu11",
574 "defines": [ "CURL_STATICLIB", "LIBARCHIVE_STATIC" ],
575 "includePath": [ { "path": "/tmp/build/Utilities" }, <...> ],
576 "isGenerated": false,
577 "language": "C",
578 "sources": [ "fld_arg.c", <...> ]
579 }
580 ],
581 "fullName": "libcmForm.a",
582 "linkerLanguage": "C",
583 "name": "cmForm",
584 "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
585 "type": "STATIC_LIBRARY"
586 }
587 ]
588 },
589 <...>
590 ]
591 }
592 ],
593 "cookie": "",
594 "inReplyTo": "codemodel",
595 "type": "reply"
596 }
597 ]== "CMake Server" ==]
598 Type “ctestInfo”
600 The “ctestInfo” request can be used after a project was “compute”d suc‐
601 cessfully.
602 It will list the complete project test structure as it is known to
604 cmake.
605 The reply will contain a key “configurations”, which will contain a
607 list of configuration objects. Configuration objects are used to des‐
608 tinquish between different configurations the build directory might
609 have enabled. While most generators only support one configuration,
610 others might support several.
611 Each configuration object can have the following keys:
613 “name” contains the name of the configuration. The name may be empty.
615 “projects”
617 contains a list of project objects, one for each build project.
618 Project objects define one (sub-)project defined in the cmake build
620 system.
621 Each project object can have the following keys:
623 “name” contains the (sub-)projects name.
625 “ctestInfo”
627 contains a list of test objects.
628 Each test object can have the following keys:
630 “ctestName”
632 contains the name of the test.
633 “ctestCommand”
635 contains the test command.
636 “properties”
638 contains a list of test property objects.
639 Each test property object can have the following keys:
641 “key” contains the test property key.
643 “value”
645 contains the test property value.
646 Type “cmakeInputs”
648 The “cmakeInputs” requests will report files used by CMake as part of
649 the build system itself.
650 This request is only available after a project was successfully “con‐
652 figure”d.
653 Example:
655 [== "CMake Server" ==[
657 {"type":"cmakeInputs"}
658 ]== "CMake Server" ==]
659 CMake will reply with the following information:
661 [== "CMake Server" ==[
663 {"buildFiles":
664 [
665 {"isCMake":true,"isTemporary":false,"sources":["/usr/lib/cmake/...", ... ]},
666 {"isCMake":false,"isTemporary":false,"sources":["CMakeLists.txt", ...]},
667 {"isCMake":false,"isTemporary":true,"sources":["/tmp/build/CMakeFiles/...", ...]}
668 ],
669 "cmakeRootDirectory":"/usr/lib/cmake",
670 "sourceDirectory":"/home/code/src/cmake",
671 "cookie":"",
672 "inReplyTo":"cmakeInputs",
673 "type":"reply"
674 }
675 ]== "CMake Server" ==]
676 All file names are either relative to the top level source directory or
678 absolute.
679 The list of files which “isCMake” set to true are part of the cmake
681 installation.
682 The list of files witch “isTemporary” set to true are part of the build
684 directory and will not survive the build directory getting cleaned out.
685 Type “cache”
687 The “cache” request will list the cached configuration values.
688 Example:
690 [== "CMake Server" ==[
692 {"type":"cache"}
693 ]== "CMake Server" ==]
694 CMake will respond with the following output:
696 [== "CMake Server" ==[
698 {
699 "cookie":"","inReplyTo":"cache","type":"reply",
700 "cache":
701 [
702 {
703 "key":"SOMEVALUE",
704 "properties":
705 {
706 "ADVANCED":"1",
707 "HELPSTRING":"This is not helpful"
708 }
709 "type":"STRING",
710 "value":"TEST"}
711 ]
712 }
713 ]== "CMake Server" ==]
714 The output can be limited to a list of keys by passing an array of key
716 names to the “keys” optional field of the “cache” request.
717 Type “fileSystemWatchers”
719 The server can watch the filesystem for changes. The “fileSystemWatch‐
720 ers” command will report on the files and directories watched.
721 Example:
723 [== "CMake Server" ==[
725 {"type":"fileSystemWatchers"}
726 ]== "CMake Server" ==]
727 CMake will respond with the following output:
729 [== "CMake Server" ==[
731 {
732 "cookie":"","inReplyTo":"fileSystemWatchers","type":"reply",
733 "watchedFiles": [ "/absolute/path" ],
734 "watchedDirectories": [ "/absolute" ]
735 }
736 ]== "CMake Server" ==]
737
739 2000-2021 Kitware, Inc. and Contributors
7403.19.7 Mar 15, 2021 CMAKE-SERVER(7)