1CMAKE-SERVER(7) CMake CMAKE-SERVER(7)
2
6 cmake-server - CMake Server
7
9 cmake(1) is capable of providing semantic information about CMake code
10 it executes to generate a buildsystem. If executed with the -E server
11 command line options, it starts in a long running mode and allows a
12 client to request the available information via a JSON protocol.
13 The protocol is designed to be useful to IDEs, refactoring tools, and
15 other tools which have a need to understand the buildsystem in
16 entirety.
17 A single cmake-buildsystem(7) may describe buildsystem contents and
19 build properties which differ based on generation-time context includ‐
20 ing:
21 · The Platform (eg, Windows, APPLE, Linux).
23 · The build configuration (eg, Debug, Release, Coverage).
25 · The Compiler (eg, MSVC, GCC, Clang) and compiler version.
27 · The language of the source files compiled.
29 · Available compile features (eg CXX variadic templates).
31 · CMake policies.
33 The protocol aims to provide information to tooling to satisfy several
35 needs:
36 1. Provide a complete and easily parsed source of all information rele‐
38 vant to the tooling as it relates to the source code. There should
39 be no need for tooling to parse generated buildsystems to access
40 include directories or compile definitions for example.
41 2. Semantic information about the CMake buildsystem itself.
43 3. Provide a stable interface for reading the information in the CMake
45 cache.
46 4. Information for determining when cmake needs to be re-run as a
48 result of file changes.
49
51 Start cmake(1) in the server command mode, supplying the path to the
52 build directory to process:
53 cmake -E server (--debug|--pipe=<NAMED_PIPE>)
55 The server will communicate using stdin/stdout (with the --debug param‐
57 eter) or using a named pipe (with the --pipe=<NAMED_PIPE> parameter).
58 Note that “named pipe” refers to a local domain socket on Unix and to a
59 named pipe on Windows.
60 When connecting to the server (via named pipe or by starting it in
62 --debug mode), the server will reply with a hello message:
63 [== "CMake Server" ==[
65 {"supportedProtocolVersions":[{"major":1,"minor":0}],"type":"hello"}
66 ]== "CMake Server" ==]
67 Messages sent to and from the process are wrapped in magic strings:
69 [== "CMake Server" ==[
71 {
72 ... some JSON message ...
73 }
74 ]== "CMake Server" ==]
75 The server is now ready to accept further requests via the named pipe
77 or stdin.
78
80 CMake server mode can be asked to provide statistics on execution
81 times, etc. or to dump a copy of the response into a file. This is
82 done passing a “debug” JSON object as a child of the request.
83 The debug object supports the “showStats” key, which takes a boolean
85 and makes the server mode return a “zzzDebug” object with stats as part
86 of its response. “dumpToFile” takes a string value and will cause the
87 cmake server to copy the response into the given filename.
88 This is a response from the cmake server with “showStats” set to true:
90 [== "CMake Server" ==[
92 {
93 "cookie":"",
94 "errorMessage":"Waiting for type \"handshake\".",
95 "inReplyTo":"unknown",
96 "type":"error",
97 "zzzDebug": {
98 "dumpFile":"/tmp/error.txt",
99 "jsonSerialization":0.011016,
100 "size":111,
101 "totalTime":0.025995
102 }
103 }
104 ]== "CMake Server" ==]
105 The server has made a copy of this response into the file
107 /tmp/error.txt and took 0.011 seconds to turn the JSON response into a
108 string, and it took 0.025 seconds to process the request in total. The
109 reply has a size of 111 bytes.
110
112 General Message Layout
113 All messages need to have a “type” value, which identifies the type of
114 message that is passed back or forth. E.g. the initial message sent by
115 the server is of type “hello”. Messages without a type will generate an
116 response of type “error”.
117 All requests sent to the server may contain a “cookie” value. This
119 value will he handed back unchanged in all responses triggered by the
120 request.
121 All responses will contain a value “inReplyTo”, which may be empty in
123 case of parse errors, but will contain the type of the request message
124 in all other cases.
125 Type “reply”
127 This type is used by the server to reply to requests.
128 The message may – depending on the type of the original request – con‐
130 tain values.
131 Example:
133 [== "CMake Server" ==[
135 {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
136 ]== "CMake Server" ==]
137 Type “error”
139 This type is used to return an error condition to the client. It will
140 contain an “errorMessage”.
141 Example:
143 [== "CMake Server" ==[
145 {"cookie":"","errorMessage":"Protocol version not supported.","inReplyTo":"handshake","type":"error"}
146 ]== "CMake Server" ==]
147 Type “progress”
149 When the server is busy for a long time, it is polite to send back
150 replies of type “progress” to the client. These will contain a “pro‐
151 gressMessage” with a string describing the action currently taking
152 place as well as “progressMinimum”, “progressMaximum” and “progressCur‐
153 rent” with integer values describing the range of progress.
154 Messages of type “progress” will be followed by more “progress” mes‐
156 sages or with a message of type “reply” or “error” that complete the
157 request.
158 “progress” messages may not be emitted after the “reply” or “error”
160 message for the request that triggered the responses was delivered.
161 Type “message”
163 A message is triggered when the server processes a request and produces
164 some form of output that should be displayed to the user. A Message has
165 a “message” with the actual text to display as well as a “title” with a
166 suggested dialog box title.
167 Example:
169 [== "CMake Server" ==[
171 {"cookie":"","message":"Something happened.","title":"Title Text","inReplyTo":"handshake","type":"message"}
172 ]== "CMake Server" ==]
173 Type “signal”
175 The server can send signals when it detects changes in the system
176 state. Signals are of type “signal”, have an empty “cookie” and “inRe‐
177 plyTo” field and always have a “name” set to show which signal was
178 sent.
179 Specific Signals
181 The cmake server may sent signals with the following names:
182 “dirty” Signal
184 The “dirty” signal is sent whenever the server determines that the con‐
185 figuration of the project is no longer up-to-date. This happens when
186 any of the files that have an influence on the build system is changed.
187 The “dirty” signal may look like this:
189 [== "CMake Server" ==[
191 {
192 "cookie":"",
193 "inReplyTo":"",
194 "name":"dirty",
195 "type":"signal"}
196 ]== "CMake Server" ==]
197 “fileChange” Signal
199 The “fileChange” signal is sent whenever a watched file is changed. It
200 contains the “path” that has changed and a list of “properties” with
201 the kind of change that was detected. Possible changes are “change” and
202 “rename”.
203 The “fileChange” signal looks like this:
205 [== "CMake Server" ==[
207 {
208 "cookie":"",
209 "inReplyTo":"",
210 "name":"fileChange",
211 "path":"/absolute/CMakeLists.txt",
212 "properties":["change"],
213 "type":"signal"}
214 ]== "CMake Server" ==]
215 Specific Message Types
217 Type “hello”
218 The initial message send by the cmake server on startup is of type
219 “hello”. This is the only message ever sent by the server that is not
220 of type “reply”, “progress” or “error”.
221 It will contain “supportedProtocolVersions” with an array of server
223 protocol versions supported by the cmake server. These are JSON objects
224 with “major” and “minor” keys containing non-negative integer values.
225 Some versions may be marked as experimental. These will contain the
226 “isExperimental” key set to true. Enabling these requires a special
227 command line argument when starting the cmake server mode.
228 Within a “major” version all “minor” versions are fully backwards com‐
230 patible. New “minor” versions may introduce functionality in such a
231 way that existing clients of the same “major” version will continue to
232 work, provided they ignore keys in the output that they do not know
233 about.
234 Example:
236 [== "CMake Server" ==[
238 {"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"}
239 ]== "CMake Server" ==]
240 Type “handshake”
242 The first request that the client may send to the server is of type
243 “handshake”.
244 This request needs to pass one of the “supportedProtocolVersions” of
246 the “hello” type response received earlier back to the server in the
247 “protocolVersion” field. Giving the “major” version of the requested
248 protocol version will make the server use the latest minor version of
249 that protocol. Use this if you do not explicitly need to depend on a
250 specific minor version.
251 Protocol version 1.0 requires the following attributes to be set:
253 · “sourceDirectory” with a path to the sources
255 · “buildDirectory” with a path to the build directory
257 · “generator” with the generator name
259 · “extraGenerator” (optional!) with the extra generator to be used
261 · “platform” with the generator platform (if supported by the gener‐
263 ator)
264 · “toolset” with the generator toolset (if supported by the genera‐
266 tor)
267 Protocol version 1.2 makes all but the build directory optional, pro‐
269 vided there is a valid cache in the build directory that contains all
270 the other information already.
271 Example:
273 [== "CMake Server" ==[
275 {"cookie":"zimtstern","type":"handshake","protocolVersion":{"major":0},
276 "sourceDirectory":"/home/code/cmake", "buildDirectory":"/tmp/testbuild",
277 "generator":"Ninja"}
278 ]== "CMake Server" ==]
279 which will result in a response type “reply”:
281 [== "CMake Server" ==[
283 {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
284 ]== "CMake Server" ==]
285 indicating that the server is ready for action.
287 Type “globalSettings”
289 This request can be sent after the initial handshake. It will return a
290 JSON structure with information on cmake state.
291 Example:
293 [== "CMake Server" ==[
295 {"type":"globalSettings"}
296 ]== "CMake Server" ==]
297 which will result in a response type “reply”:
299 [== "CMake Server" ==[
301 {
302 "buildDirectory": "/tmp/test-build",
303 "capabilities": {
304 "generators": [
305 {
306 "extraGenerators": [],
307 "name": "Watcom WMake",
308 "platformSupport": false,
309 "toolsetSupport": false
310 },
311 <...>
312 ],
313 "serverMode": false,
314 "version": {
315 "isDirty": false,
316 "major": 3,
317 "minor": 6,
318 "patch": 20160830,
319 "string": "3.6.20160830-gd6abad",
320 "suffix": "gd6abad"
321 }
322 },
323 "checkSystemVars": false,
324 "cookie": "",
325 "extraGenerator": "",
326 "generator": "Ninja",
327 "debugOutput": false,
328 "inReplyTo": "globalSettings",
329 "sourceDirectory": "/home/code/cmake",
330 "trace": false,
331 "traceExpand": false,
332 "type": "reply",
333 "warnUninitialized": false,
334 "warnUnused": false,
335 "warnUnusedCli": true
336 }
337 ]== "CMake Server" ==]
338 Type “setGlobalSettings”
340 This request can be sent to change the global settings attributes.
341 Unknown attributes are going to be ignored. Read-only attributes
342 reported by “globalSettings” are all capabilities, buildDirectory, gen‐
343 erator, extraGenerator and sourceDirectory. Any attempt to set these
344 will be ignored, too.
345 All other settings will be changed.
347 The server will respond with an empty reply message or an error.
349 Example:
351 [== "CMake Server" ==[
353 {"type":"setGlobalSettings","debugOutput":true}
354 ]== "CMake Server" ==]
355 CMake will reply to this with:
357 [== "CMake Server" ==[
359 {"inReplyTo":"setGlobalSettings","type":"reply"}
360 ]== "CMake Server" ==]
361 Type “configure”
363 This request will configure a project for build.
364 To configure a build directory already containing cmake files, it is
366 enough to set “buildDirectory” via “setGlobalSettings”. To create a
367 fresh build directory you also need to set “currentGenerator” and
368 “sourceDirectory” via “setGlobalSettings” in addition to “buildDirec‐
369 tory”.
370 You may a list of strings to “configure” via the “cacheArguments” key.
372 These strings will be interpreted similar to command line arguments
373 related to cache handling that are passed to the cmake command line
374 client.
375 Example:
377 [== "CMake Server" ==[
379 {"type":"configure", "cacheArguments":["-Dsomething=else"]}
380 ]== "CMake Server" ==]
381 CMake will reply like this (after reporting progress for some time):
383 [== "CMake Server" ==[
385 {"cookie":"","inReplyTo":"configure","type":"reply"}
386 ]== "CMake Server" ==]
387 Type “compute”
389 This request will generate build system files in the build directory
390 and is only available after a project was successfully “configure”d.
391 Example:
393 [== "CMake Server" ==[
395 {"type":"compute"}
396 ]== "CMake Server" ==]
397 CMake will reply (after reporting progress information):
399 [== "CMake Server" ==[
401 {"cookie":"","inReplyTo":"compute","type":"reply"}
402 ]== "CMake Server" ==]
403 Type “codemodel”
405 The “codemodel” request can be used after a project was “compute”d suc‐
406 cessfully.
407 It will list the complete project structure as it is known to cmake.
409 The reply will contain a key “configurations”, which will contain a
411 list of configuration objects. Configuration objects are used to des‐
412 tinquish between different configurations the build directory might
413 have enabled. While most generators only support one configuration,
414 others might support several.
415 Each configuration object can have the following keys:
417 “name” contains the name of the configuration. The name may be empty.
419 “projects”
421 contains a list of project objects, one for each build project.
422 Project objects define one (sub-)project defined in the cmake build
424 system.
425 Each project object can have the following keys:
427 “name” contains the (sub-)projects name.
429 “minimumCMakeVersion”
431 contains the minimum cmake version allowed for this project,
432 null if the project doesn’t specify one.
433 “hasInstallRule”
435 true if the project contains any install rules, false otherwise.
436 “sourceDirectory”
438 contains the current source directory
439 “buildDirectory”
441 contains the current build directory.
442 “targets”
444 contains a list of build system target objects.
445 Target objects define individual build targets for a certain configura‐
447 tion.
448 Each target object can have the following keys:
450 “name” contains the name of the target.
452 “type” defines the type of build of the target. Possible values are
454 “STATIC_LIBRARY”, “MODULE_LIBRARY”, “SHARED_LIBRARY”,
455 “OBJECT_LIBRARY”, “EXECUTABLE”, “UTILITY” and “INTER‐
456 FACE_LIBRARY”.
457 “fullName”
459 contains the full name of the build result (incl. extensions,
460 etc.).
461 “sourceDirectory”
463 contains the current source directory.
464 “buildDirectory”
466 contains the current build directory.
467 “isGeneratorProvided”
469 true if the target is auto-created by a generator, false other‐
470 wise
471 “hasInstallRule”
473 true if the target contains any install rules, false otherwise.
474 “installPaths”
476 full path to the destination directories defined by target
477 install rules.
478 “artifacts”
480 with a list of build artifacts. The list is sorted with the most
481 important artifacts first (e.g. a .DLL file is listed before a
482 “linkerLanguage”
484 contains the language of the linker used to produce the arti‐
485 fact.
486 “linkLibraries”
488 with a list of libraries to link to. This value is encoded in
489 the system’s native shell format.
490 “linkFlags”
492 with a list of flags to pass to the linker. This value is
493 encoded in the system’s native shell format.
494 “linkLanguageFlags”
496 with the flags for a compiler using the linkerLanguage. This
497 value is encoded in the system’s native shell format.
498 “frameworkPath”
500 with the framework path (on Apple computers). This value is
501 encoded in the system’s native shell format.
502 “linkPath”
504 with the link path. This value is encoded in the system’s native
505 shell format.
506 “sysroot”
508 with the sysroot path.
509 “fileGroups”
511 contains the source files making up the target.
512 FileGroups are used to group sources using similar settings together.
514 Each fileGroup object may contain the following keys:
516 “language”
518 contains the programming language used by all files in the
519 group.
520 “compileFlags”
522 with a string containing all the flags passed to the compiler
523 when building any of the files in this group. This value is
524 encoded in the system’s native shell format.
525 “includePath”
527 with a list of include paths. Each include path is an object
528 containing a “path” with the actual include path and “isSystem”
529 with a bool value informing whether this is a normal include or
530 a system include. This value is encoded in the system’s native
531 shell format.
532 “defines”
534 with a list of defines in the form “SOMEVALUE” or
535 “SOMEVALUE=42”. This value is encoded in the system’s native
536 shell format.
537 “sources”
539 with a list of source files.
540 All file paths in the fileGroup are either absolute or relative to the
542 sourceDirectory of the target.
543 Example:
545 [== "CMake Server" ==[
547 {"type":"codemodel"}
548 ]== "CMake Server" ==]
549 CMake will reply:
551 [== "CMake Server" ==[
553 {
554 "configurations": [
555 {
556 "name": "",
557 "projects": [
558 {
559 "buildDirectory": "/tmp/build/Source/CursesDialog/form",
560 "name": "CMAKE_FORM",
561 "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
562 "targets": [
563 {
564 "artifacts": [ "/tmp/build/Source/CursesDialog/form/libcmForm.a" ],
565 "buildDirectory": "/tmp/build/Source/CursesDialog/form",
566 "fileGroups": [
567 {
568 "compileFlags": " -std=gnu11",
569 "defines": [ "CURL_STATICLIB", "LIBARCHIVE_STATIC" ],
570 "includePath": [ { "path": "/tmp/build/Utilities" }, <...> ],
571 "isGenerated": false,
572 "language": "C",
573 "sources": [ "fld_arg.c", <...> ]
574 }
575 ],
576 "fullName": "libcmForm.a",
577 "linkerLanguage": "C",
578 "name": "cmForm",
579 "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
580 "type": "STATIC_LIBRARY"
581 }
582 ]
583 },
584 <...>
585 ]
586 }
587 ],
588 "cookie": "",
589 "inReplyTo": "codemodel",
590 "type": "reply"
591 }
592 ]== "CMake Server" ==]
593 Type “ctestInfo”
595 The “ctestInfo” request can be used after a project was “compute”d suc‐
596 cessfully.
597 It will list the complete project test structure as it is known to
599 cmake.
600 The reply will contain a key “configurations”, which will contain a
602 list of configuration objects. Configuration objects are used to des‐
603 tinquish between different configurations the build directory might
604 have enabled. While most generators only support one configuration,
605 others might support several.
606 Each configuration object can have the following keys:
608 “name” contains the name of the configuration. The name may be empty.
610 “projects”
612 contains a list of project objects, one for each build project.
613 Project objects define one (sub-)project defined in the cmake build
615 system.
616 Each project object can have the following keys:
618 “name” contains the (sub-)projects name.
620 “ctestInfo”
622 contains a list of test objects.
623 Each test object can have the following keys:
625 “ctestName”
627 contains the name of the test.
628 “ctestCommand”
630 contains the test command.
631 “properties”
633 contains a list of test property objects.
634 Each test property object can have the following keys:
636 “key” contains the test property key.
638 “value”
640 contains the test property value.
641 Type “cmakeInputs”
643 The “cmakeInputs” requests will report files used by CMake as part of
644 the build system itself.
645 This request is only available after a project was successfully “con‐
647 figure”d.
648 Example:
650 [== "CMake Server" ==[
652 {"type":"cmakeInputs"}
653 ]== "CMake Server" ==]
654 CMake will reply with the following information:
656 [== "CMake Server" ==[
658 {"buildFiles":
659 [
660 {"isCMake":true,"isTemporary":false,"sources":["/usr/lib/cmake/...", ... ]},
661 {"isCMake":false,"isTemporary":false,"sources":["CMakeLists.txt", ...]},
662 {"isCMake":false,"isTemporary":true,"sources":["/tmp/build/CMakeFiles/...", ...]}
663 ],
664 "cmakeRootDirectory":"/usr/lib/cmake",
665 "sourceDirectory":"/home/code/src/cmake",
666 "cookie":"",
667 "inReplyTo":"cmakeInputs",
668 "type":"reply"
669 }
670 ]== "CMake Server" ==]
671 All file names are either relative to the top level source directory or
673 absolute.
674 The list of files which “isCMake” set to true are part of the cmake
676 installation.
677 The list of files witch “isTemporary” set to true are part of the build
679 directory and will not survive the build directory getting cleaned out.
680 Type “cache”
682 The “cache” request will list the cached configuration values.
683 Example:
685 [== "CMake Server" ==[
687 {"type":"cache"}
688 ]== "CMake Server" ==]
689 CMake will respond with the following output:
691 [== "CMake Server" ==[
693 {
694 "cookie":"","inReplyTo":"cache","type":"reply",
695 "cache":
696 [
697 {
698 "key":"SOMEVALUE",
699 "properties":
700 {
701 "ADVANCED":"1",
702 "HELPSTRING":"This is not helpful"
703 }
704 "type":"STRING",
705 "value":"TEST"}
706 ]
707 }
708 ]== "CMake Server" ==]
709 The output can be limited to a list of keys by passing an array of key
711 names to the “keys” optional field of the “cache” request.
712 Type “fileSystemWatchers”
714 The server can watch the filesystem for changes. The “fileSystemWatch‐
715 ers” command will report on the files and directories watched.
716 Example:
718 [== "CMake Server" ==[
720 {"type":"fileSystemWatchers"}
721 ]== "CMake Server" ==]
722 CMake will respond with the following output:
724 [== "CMake Server" ==[
726 {
727 "cookie":"","inReplyTo":"fileSystemWatchers","type":"reply",
728 "watchedFiles": [ "/absolute/path" ],
729 "watchedDirectories": [ "/absolute" ]
730 }
731 ]== "CMake Server" ==]
732
734 2000-2019 Kitware, Inc. and Contributors
7353.14.5 Jun 01, 2019 CMAKE-SERVER(7)