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 When connecting to the server (via named pipe or by starting it in
60 --debug mode), the server will reply with a hello message:
61 [== "CMake Server" ==[
63 {"supportedProtocolVersions":[{"major":1,"minor":0}],"type":"hello"}
64 ]== "CMake Server" ==]
65 Messages sent to and from the process are wrapped in magic strings:
67 [== "CMake Server" ==[
69 {
70 ... some JSON message ...
71 }
72 ]== "CMake Server" ==]
73 The server is now ready to accept further requests via the named pipe
75 or stdin.
76
78 CMake server mode can be asked to provide statistics on execution
79 times, etc. or to dump a copy of the response into a file. This is
80 done passing a “debug” JSON object as a child of the request.
81 The debug object supports the “showStats” key, which takes a boolean
83 and makes the server mode return a “zzzDebug” object with stats as part
84 of its response. “dumpToFile” takes a string value and will cause the
85 cmake server to copy the response into the given filename.
86 This is a response from the cmake server with “showStats” set to true:
88 [== "CMake Server" ==[
90 {
91 "cookie":"",
92 "errorMessage":"Waiting for type \"handshake\".",
93 "inReplyTo":"unknown",
94 "type":"error",
95 "zzzDebug": {
96 "dumpFile":"/tmp/error.txt",
97 "jsonSerialization":0.011016,
98 "size":111,
99 "totalTime":0.025995
100 }
101 }
102 ]== "CMake Server" ==]
103 The server has made a copy of this response into the file
105 /tmp/error.txt and took 0.011 seconds to turn the JSON response into a
106 string, and it took 0.025 seconds to process the request in total. The
107 reply has a size of 111 bytes.
108
110 General Message Layout
111 All messages need to have a “type” value, which identifies the type of
112 message that is passed back or forth. E.g. the initial message sent by
113 the server is of type “hello”. Messages without a type will generate an
114 response of type “error”.
115 All requests sent to the server may contain a “cookie” value. This
117 value will he handed back unchanged in all responses triggered by the
118 request.
119 All responses will contain a value “inReplyTo”, which may be empty in
121 case of parse errors, but will contain the type of the request message
122 in all other cases.
123 Type “reply”
125 This type is used by the server to reply to requests.
126 The message may – depending on the type of the original request – con‐
128 tain values.
129 Example:
131 [== "CMake Server" ==[
133 {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
134 ]== "CMake Server" ==]
135 Type “error”
137 This type is used to return an error condition to the client. It will
138 contain an “errorMessage”.
139 Example:
141 [== "CMake Server" ==[
143 {"cookie":"","errorMessage":"Protocol version not supported.","inReplyTo":"handshake","type":"error"}
144 ]== "CMake Server" ==]
145 Type “progress”
147 When the server is busy for a long time, it is polite to send back
148 replies of type “progress” to the client. These will contain a “pro‐
149 gressMessage” with a string describing the action currently taking
150 place as well as “progressMinimum”, “progressMaximum” and “progressCur‐
151 rent” with integer values describing the range of progress.
152 Messages of type “progress” will be followed by more “progress” mes‐
154 sages or with a message of type “reply” or “error” that complete the
155 request.
156 “progress” messages may not be emitted after the “reply” or “error”
158 message for the request that triggered the responses was delivered.
159 Type “message”
161 A message is triggered when the server processes a request and produces
162 some form of output that should be displayed to the user. A Message has
163 a “message” with the actual text to display as well as a “title” with a
164 suggested dialog box title.
165 Example:
167 [== "CMake Server" ==[
169 {"cookie":"","message":"Something happened.","title":"Title Text","inReplyTo":"handshake","type":"message"}
170 ]== "CMake Server" ==]
171 Type “signal”
173 The server can send signals when it detects changes in the system
174 state. Signals are of type “signal”, have an empty “cookie” and “inRe‐
175 plyTo” field and always have a “name” set to show which signal was
176 sent.
177 Specific Signals
179 The cmake server may sent signals with the following names:
180 “dirty” Signal
182 The “dirty” signal is sent whenever the server determines that the con‐
183 figuration of the project is no longer up-to-date. This happens when
184 any of the files that have an influence on the build system is changed.
185 The “dirty” signal may look like this:
187 [== "CMake Server" ==[
189 {
190 "cookie":"",
191 "inReplyTo":"",
192 "name":"dirty",
193 "type":"signal"}
194 ]== "CMake Server" ==]
195 “fileChange” Signal
197 The “fileChange” signal is sent whenever a watched file is changed. It
198 contains the “path” that has changed and a list of “properties” with
199 the kind of change that was detected. Possible changes are “change” and
200 “rename”.
201 The “fileChange” signal looks like this:
203 [== "CMake Server" ==[
205 {
206 "cookie":"",
207 "inReplyTo":"",
208 "name":"fileChange",
209 "path":"/absolute/CMakeLists.txt",
210 "properties":["change"],
211 "type":"signal"}
212 ]== "CMake Server" ==]
213 Specific Message Types
215 Type “hello”
216 The initial message send by the cmake server on startup is of type
217 “hello”. This is the only message ever sent by the server that is not
218 of type “reply”, “progress” or “error”.
219 It will contain “supportedProtocolVersions” with an array of server
221 protocol versions supported by the cmake server. These are JSON objects
222 with “major” and “minor” keys containing non-negative integer values.
223 Some versions may be marked as experimental. These will contain the
224 “isExperimental” key set to true. Enabling these requires a special
225 command line argument when starting the cmake server mode.
226 Within a “major” version all “minor” versions are fully backwards com‐
228 patible. New “minor” versions may introduce functionality in such a
229 way that existing clients of the same “major” version will continue to
230 work, provided they ignore keys in the output that they do not know
231 about.
232 Example:
234 [== "CMake Server" ==[
236 {"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"}
237 ]== "CMake Server" ==]
238 Type “handshake”
240 The first request that the client may send to the server is of type
241 “handshake”.
242 This request needs to pass one of the “supportedProtocolVersions” of
244 the “hello” type response received earlier back to the server in the
245 “protocolVersion” field. Giving the “major” version of the requested
246 protocol version will make the server use the latest minor version of
247 that protocol. Use this if you do not explicitly need to depend on a
248 specific minor version.
249 Protocol version 1.0 requires the following attributes to be set:
251 · “sourceDirectory” with a path to the sources
253 · “buildDirectory” with a path to the build directory
255 · “generator” with the generator name
257 · “extraGenerator” (optional!) with the extra generator to be used
259 · “platform” with the generator platform (if supported by the gener‐
261 ator)
262 · “toolset” with the generator toolset (if supported by the genera‐
264 tor)
265 Protocol version 1.2 makes all but the build directory optional, pro‐
267 vided there is a valid cache in the build directory that contains all
268 the other information already.
269 Example:
271 [== "CMake Server" ==[
273 {"cookie":"zimtstern","type":"handshake","protocolVersion":{"major":0},
274 "sourceDirectory":"/home/code/cmake", "buildDirectory":"/tmp/testbuild",
275 "generator":"Ninja"}
276 ]== "CMake Server" ==]
277 which will result in a response type “reply”:
279 [== "CMake Server" ==[
281 {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
282 ]== "CMake Server" ==]
283 indicating that the server is ready for action.
285 Type “globalSettings”
287 This request can be sent after the initial handshake. It will return a
288 JSON structure with information on cmake state.
289 Example:
291 [== "CMake Server" ==[
293 {"type":"globalSettings"}
294 ]== "CMake Server" ==]
295 which will result in a response type “reply”:
297 [== "CMake Server" ==[
299 {
300 "buildDirectory": "/tmp/test-build",
301 "capabilities": {
302 "generators": [
303 {
304 "extraGenerators": [],
305 "name": "Watcom WMake",
306 "platformSupport": false,
307 "toolsetSupport": false
308 },
309 <...>
310 ],
311 "serverMode": false,
312 "version": {
313 "isDirty": false,
314 "major": 3,
315 "minor": 6,
316 "patch": 20160830,
317 "string": "3.6.20160830-gd6abad",
318 "suffix": "gd6abad"
319 }
320 },
321 "checkSystemVars": false,
322 "cookie": "",
323 "extraGenerator": "",
324 "generator": "Ninja",
325 "debugOutput": false,
326 "inReplyTo": "globalSettings",
327 "sourceDirectory": "/home/code/cmake",
328 "trace": false,
329 "traceExpand": false,
330 "type": "reply",
331 "warnUninitialized": false,
332 "warnUnused": false,
333 "warnUnusedCli": true
334 }
335 ]== "CMake Server" ==]
336 Type “setGlobalSettings”
338 This request can be sent to change the global settings attributes.
339 Unknown attributes are going to be ignored. Read-only attributes
340 reported by “globalSettings” are all capabilities, buildDirectory, gen‐
341 erator, extraGenerator and sourceDirectory. Any attempt to set these
342 will be ignored, too.
343 All other settings will be changed.
345 The server will respond with an empty reply message or an error.
347 Example:
349 [== "CMake Server" ==[
351 {"type":"setGlobalSettings","debugOutput":true}
352 ]== "CMake Server" ==]
353 CMake will reply to this with:
355 [== "CMake Server" ==[
357 {"inReplyTo":"setGlobalSettings","type":"reply"}
358 ]== "CMake Server" ==]
359 Type “configure”
361 This request will configure a project for build.
362 To configure a build directory already containing cmake files, it is
364 enough to set “buildDirectory” via “setGlobalSettings”. To create a
365 fresh build directory you also need to set “currentGenerator” and
366 “sourceDirectory” via “setGlobalSettings” in addition to “buildDirec‐
367 tory”.
368 You may a list of strings to “configure” via the “cacheArguments” key.
370 These strings will be interpreted similar to command line arguments
371 related to cache handling that are passed to the cmake command line
372 client.
373 Example:
375 [== "CMake Server" ==[
377 {"type":"configure", "cacheArguments":["-Dsomething=else"]}
378 ]== "CMake Server" ==]
379 CMake will reply like this (after reporting progress for some time):
381 [== "CMake Server" ==[
383 {"cookie":"","inReplyTo":"configure","type":"reply"}
384 ]== "CMake Server" ==]
385 Type “compute”
387 This request will generate build system files in the build directory
388 and is only available after a project was successfully “configure”d.
389 Example:
391 [== "CMake Server" ==[
393 {"type":"compute"}
394 ]== "CMake Server" ==]
395 CMake will reply (after reporting progress information):
397 [== "CMake Server" ==[
399 {"cookie":"","inReplyTo":"compute","type":"reply"}
400 ]== "CMake Server" ==]
401 Type “codemodel”
403 The “codemodel” request can be used after a project was “compute”d suc‐
404 cessfully.
405 It will list the complete project structure as it is known to cmake.
407 The reply will contain a key “configurations”, which will contain a
409 list of configuration objects. Configuration objects are used to des‐
410 tinquish between different configurations the build directory might
411 have enabled. While most generators only support one configuration,
412 others might support several.
413 Each configuration object can have the following keys:
415 “name” contains the name of the configuration. The name may be empty.
417 “projects”
419 contains a list of project objects, one for each build project.
420 Project objects define one (sub-)project defined in the cmake build
422 system.
423 Each project object can have the following keys:
425 “name” contains the (sub-)projects name.
427 “minimumCMakeVersion”
429 contains the minimum cmake version allowed for this project,
430 null if the project doesn’t specify one.
431 “hasInstallRule”
433 true if the project contains any install rules, false otherwise.
434 “sourceDirectory”
436 contains the current source directory
437 “buildDirectory”
439 contains the current build directory.
440 “targets”
442 contains a list of build system target objects.
443 Target objects define individual build targets for a certain configura‐
445 tion.
446 Each target object can have the following keys:
448 “name” contains the name of the target.
450 “type” defines the type of build of the target. Possible values are
452 “STATIC_LIBRARY”, “MODULE_LIBRARY”, “SHARED_LIBRARY”,
453 “OBJECT_LIBRARY”, “EXECUTABLE”, “UTILITY” and “INTER‐
454 FACE_LIBRARY”.
455 “fullName”
457 contains the full name of the build result (incl. extensions,
458 etc.).
459 “sourceDirectory”
461 contains the current source directory.
462 “buildDirectory”
464 contains the current build directory.
465 “isGeneratorProvided”
467 true if the target is auto-created by a generator, false other‐
468 wise
469 “hasInstallRule”
471 true if the target contains any install rules, false otherwise.
472 “installPaths”
474 full path to the destination directories defined by target
475 install rules.
476 “artifacts”
478 with a list of build artifacts. The list is sorted with the most
479 important artifacts first (e.g. a .DLL file is listed before a
480 “linkerLanguage”
482 contains the language of the linker used to produce the arti‐
483 fact.
484 “linkLibraries”
486 with a list of libraries to link to. This value is encoded in
487 the system’s native shell format.
488 “linkFlags”
490 with a list of flags to pass to the linker. This value is
491 encoded in the system’s native shell format.
492 “linkLanguageFlags”
494 with the flags for a compiler using the linkerLanguage. This
495 value is encoded in the system’s native shell format.
496 “frameworkPath”
498 with the framework path (on Apple computers). This value is
499 encoded in the system’s native shell format.
500 “linkPath”
502 with the link path. This value is encoded in the system’s native
503 shell format.
504 “sysroot”
506 with the sysroot path.
507 “fileGroups”
509 contains the source files making up the target.
510 FileGroups are used to group sources using similar settings together.
512 Each fileGroup object may contain the following keys:
514 “language”
516 contains the programming language used by all files in the
517 group.
518 “compileFlags”
520 with a string containing all the flags passed to the compiler
521 when building any of the files in this group. This value is
522 encoded in the system’s native shell format.
523 “includePath”
525 with a list of include paths. Each include path is an object
526 containing a “path” with the actual include path and “isSystem”
527 with a bool value informing whether this is a normal include or
528 a system include. This value is encoded in the system’s native
529 shell format.
530 “defines”
532 with a list of defines in the form “SOMEVALUE” or
533 “SOMEVALUE=42”. This value is encoded in the system’s native
534 shell format.
535 “sources”
537 with a list of source files.
538 All file paths in the fileGroup are either absolute or relative to the
540 sourceDirectory of the target.
541 Example:
543 [== "CMake Server" ==[
545 {"type":"codemodel"}
546 ]== "CMake Server" ==]
547 CMake will reply:
549 [== "CMake Server" ==[
551 {
552 "configurations": [
553 {
554 "name": "",
555 "projects": [
556 {
557 "buildDirectory": "/tmp/build/Source/CursesDialog/form",
558 "name": "CMAKE_FORM",
559 "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
560 "targets": [
561 {
562 "artifacts": [ "/tmp/build/Source/CursesDialog/form/libcmForm.a" ],
563 "buildDirectory": "/tmp/build/Source/CursesDialog/form",
564 "fileGroups": [
565 {
566 "compileFlags": " -std=gnu11",
567 "defines": [ "CURL_STATICLIB", "LIBARCHIVE_STATIC" ],
568 "includePath": [ { "path": "/tmp/build/Utilities" }, <...> ],
569 "isGenerated": false,
570 "language": "C",
571 "sources": [ "fld_arg.c", <...> ]
572 }
573 ],
574 "fullName": "libcmForm.a",
575 "linkerLanguage": "C",
576 "name": "cmForm",
577 "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
578 "type": "STATIC_LIBRARY"
579 }
580 ]
581 },
582 <...>
583 ]
584 }
585 ],
586 "cookie": "",
587 "inReplyTo": "codemodel",
588 "type": "reply"
589 }
590 ]== "CMake Server" ==]
591 Type “ctestInfo”
593 The “ctestInfo” request can be used after a project was “compute”d suc‐
594 cessfully.
595 It will list the complete project test structure as it is known to
597 cmake.
598 The reply will contain a key “configurations”, which will contain a
600 list of configuration objects. Configuration objects are used to des‐
601 tinquish between different configurations the build directory might
602 have enabled. While most generators only support one configuration,
603 others might support several.
604 Each configuration object can have the following keys:
606 “name” contains the name of the configuration. The name may be empty.
608 “projects”
610 contains a list of project objects, one for each build project.
611 Project objects define one (sub-)project defined in the cmake build
613 system.
614 Each project object can have the following keys:
616 “name” contains the (sub-)projects name.
618 “ctestInfo”
620 contains a list of test objects.
621 Each test object can have the following keys:
623 “ctestName”
625 contains the name of the test.
626 “ctestCommand”
628 contains the test command.
629 “properties”
631 contains a list of test property objects.
632 Each test property object can have the following keys:
634 “key” contains the test property key.
636 “value”
638 contains the test property value.
639 Type “cmakeInputs”
641 The “cmakeInputs” requests will report files used by CMake as part of
642 the build system itself.
643 This request is only available after a project was successfully “con‐
645 figure”d.
646 Example:
648 [== "CMake Server" ==[
650 {"type":"cmakeInputs"}
651 ]== "CMake Server" ==]
652 CMake will reply with the following information:
654 [== "CMake Server" ==[
656 {"buildFiles":
657 [
658 {"isCMake":true,"isTemporary":false,"sources":["/usr/lib/cmake/...", ... ]},
659 {"isCMake":false,"isTemporary":false,"sources":["CMakeLists.txt", ...]},
660 {"isCMake":false,"isTemporary":true,"sources":["/tmp/build/CMakeFiles/...", ...]}
661 ],
662 "cmakeRootDirectory":"/usr/lib/cmake",
663 "sourceDirectory":"/home/code/src/cmake",
664 "cookie":"",
665 "inReplyTo":"cmakeInputs",
666 "type":"reply"
667 }
668 ]== "CMake Server" ==]
669 All file names are either relative to the top level source directory or
671 absolute.
672 The list of files which “isCMake” set to true are part of the cmake
674 installation.
675 The list of files witch “isTemporary” set to true are part of the build
677 directory and will not survive the build directory getting cleaned out.
678 Type “cache”
680 The “cache” request will list the cached configuration values.
681 Example:
683 [== "CMake Server" ==[
685 {"type":"cache"}
686 ]== "CMake Server" ==]
687 CMake will respond with the following output:
689 [== "CMake Server" ==[
691 {
692 "cookie":"","inReplyTo":"cache","type":"reply",
693 "cache":
694 [
695 {
696 "key":"SOMEVALUE",
697 "properties":
698 {
699 "ADVANCED":"1",
700 "HELPSTRING":"This is not helpful"
701 }
702 "type":"STRING",
703 "value":"TEST"}
704 ]
705 }
706 ]== "CMake Server" ==]
707 The output can be limited to a list of keys by passing an array of key
709 names to the “keys” optional field of the “cache” request.
710 Type “fileSystemWatchers”
712 The server can watch the filesystem for changes. The “fileSystemWatch‐
713 ers” command will report on the files and directories watched.
714 Example:
716 [== "CMake Server" ==[
718 {"type":"fileSystemWatchers"}
719 ]== "CMake Server" ==]
720 CMake will respond with the following output:
722 [== "CMake Server" ==[
724 {
725 "cookie":"","inReplyTo":"fileSystemWatchers","type":"reply",
726 "watchedFiles": [ "/absolute/path" ],
727 "watchedDirectories": [ "/absolute" ]
728 }
729 ]== "CMake Server" ==]
730
732 2000-2018 Kitware, Inc. and Contributors
7333.11.4 May 13, 2019 CMAKE-SERVER(7)