1CMAKE-FILE-API(7) CMake CMAKE-FILE-API(7)
2
6 cmake-file-api - CMake File-Based API
7
9 CMake provides a file-based API that clients may use to get semantic
10 information about the buildsystems CMake generates. Clients may use
11 the API by writing query files to a specific location in a build tree
12 to request zero or more Object Kinds. When CMake generates the
13 buildsystem in that build tree it will read the query files and write
14 reply files for the client to read.
15 The file-based API uses a <build>/.cmake/api/ directory at the top of a
17 build tree. The API is versioned to support changes to the layout of
18 files within the API directory. API file layout versioning is orthogo‐
19 nal to the versioning of Object Kinds used in replies. This version of
20 CMake supports only one API version, API v1.
21
23 API v1 is housed in the <build>/.cmake/api/v1/ directory. It has the
24 following subdirectories:
25 query/ Holds query files written by clients. These may be v1 Shared
27 Stateless Query Files, v1 Client Stateless Query Files, or v1
28 Client Stateful Query Files.
29 reply/ Holds reply files written by CMake whenever it runs to generate
31 a build system. These are indexed by a v1 Reply Index File file
32 that may reference additional v1 Reply Files. CMake owns all
33 reply files. Clients must never remove them.
34 Clients may look for and read a reply index file at any time.
36 Clients may optionally create the reply/ directory at any time
37 and monitor it for the appearance of a new reply index file.
38 v1 Shared Stateless Query Files
40 Shared stateless query files allow clients to share requests for major
41 versions of the Object Kinds and get all requested versions recognized
42 by the CMake that runs.
43 Clients may create shared requests by creating empty files in the
45 v1/query/ directory. The form is:
46 <build>/.cmake/api/v1/query/<kind>-v<major>
48 where <kind> is one of the Object Kinds, -v is literal, and <major> is
50 the major version number.
51 Files of this form are stateless shared queries not owned by any spe‐
53 cific client. Once created they should not be removed without external
54 client coordination or human intervention.
55 v1 Client Stateless Query Files
57 Client stateless query files allow clients to create owned requests for
58 major versions of the Object Kinds and get all requested versions rec‐
59 ognized by the CMake that runs.
60 Clients may create owned requests by creating empty files in
62 client-specific query subdirectories. The form is:
63 <build>/.cmake/api/v1/query/client-<client>/<kind>-v<major>
65 where client- is literal, <client> is a string uniquely identifying the
67 client, <kind> is one of the Object Kinds, -v is literal, and <major>
68 is the major version number. Each client must choose a unique <client>
69 identifier via its own means.
70 Files of this form are stateless queries owned by the client <client>.
72 The owning client may remove them at any time.
73 v1 Client Stateful Query Files
75 Stateful query files allow clients to request a list of versions of
76 each of the Object Kinds and get only the most recent version recog‐
77 nized by the CMake that runs.
78 Clients may create owned stateful queries by creating query.json files
80 in client-specific query subdirectories. The form is:
81 <build>/.cmake/api/v1/query/client-<client>/query.json
83 where client- is literal, <client> is a string uniquely identifying the
85 client, and query.json is literal. Each client must choose a unique
86 <client> identifier via its own means.
87 query.json files are stateful queries owned by the client <client>.
89 The owning client may update or remove them at any time. When a given
90 client installation is updated it may then update the stateful query it
91 writes to build trees to request newer object versions. This can be
92 used to avoid asking CMake to generate multiple object versions unnec‐
93 essarily.
94 A query.json file must contain a JSON object:
96 {
98 "requests": [
99 { "kind": "<kind>" , "version": 1 },
100 { "kind": "<kind>" , "version": { "major": 1, "minor": 2 } },
101 { "kind": "<kind>" , "version": [2, 1] },
102 { "kind": "<kind>" , "version": [2, { "major": 1, "minor": 2 }] },
103 { "kind": "<kind>" , "version": 1, "client": {} },
104 { "kind": "..." }
105 ],
106 "client": {}
107 }
108 The members are:
110 requests
112 A JSON array containing zero or more requests. Each request is
113 a JSON object with members:
114 kind Specifies one of the Object Kinds to be included in the
116 reply.
117 version
119 Indicates the version(s) of the object kind that the
120 client understands. Versions have major and minor compo‐
121 nents following semantic version conventions. The value
122 must be
123 • a JSON integer specifying a (non-negative) major ver‐
125 sion number, or
126 • a JSON object containing major and (optionally) minor
128 members specifying non-negative integer version compo‐
129 nents, or
130 • a JSON array whose elements are each one of the above.
132 client Optional member reserved for use by the client. This
134 value is preserved in the reply written for the client in
135 the v1 Reply Index File but is otherwise ignored.
136 Clients may use this to pass custom information with a
137 request through to its reply.
138 For each requested object kind CMake will choose the first ver‐
140 sion that it recognizes for that kind among those listed in the
141 request. The response will use the selected major version with
142 the highest minor version known to the running CMake for that
143 major version. Therefore clients should list all supported ma‐
144 jor versions in preferred order along with the minimal minor
145 version required for each major version.
146 client Optional member reserved for use by the client. This value is
148 preserved in the reply written for the client in the v1 Reply
149 Index File but is otherwise ignored. Clients may use this to
150 pass custom information with a query through to its reply.
151 Other query.json top-level members are reserved for future use. If
153 present they are ignored for forward compatibility.
154 v1 Reply Index File
156 CMake writes an index-*.json file to the v1/reply/ directory whenever
157 it runs to generate a build system. Clients must read the reply index
158 file first and may read other v1 Reply Files only by following refer‐
159 ences. The form of the reply index file name is:
160 <build>/.cmake/api/v1/reply/index-<unspecified>.json
162 where index- is literal and <unspecified> is an unspecified name se‐
164 lected by CMake. Whenever a new index file is generated it is given a
165 new name and any old one is deleted. During the short time between
166 these steps there may be multiple index files present; the one with the
167 largest name in lexicographic order is the current index file.
168 The reply index file contains a JSON object:
170 {
172 "cmake": {
173 "version": {
174 "major": 3, "minor": 14, "patch": 0, "suffix": "",
175 "string": "3.14.0", "isDirty": false
176 },
177 "paths": {
178 "cmake": "/prefix/bin/cmake",
179 "ctest": "/prefix/bin/ctest",
180 "cpack": "/prefix/bin/cpack",
181 "root": "/prefix/share/cmake-3.14"
182 },
183 "generator": {
184 "multiConfig": false,
185 "name": "Unix Makefiles"
186 }
187 },
188 "objects": [
189 { "kind": "<kind>",
190 "version": { "major": 1, "minor": 0 },
191 "jsonFile": "<file>" },
192 { "...": "..." }
193 ],
194 "reply": {
195 "<kind>-v<major>": { "kind": "<kind>",
196 "version": { "major": 1, "minor": 0 },
197 "jsonFile": "<file>" },
198 "<unknown>": { "error": "unknown query file" },
199 "...": {},
200 "client-<client>": {
201 "<kind>-v<major>": { "kind": "<kind>",
202 "version": { "major": 1, "minor": 0 },
203 "jsonFile": "<file>" },
204 "<unknown>": { "error": "unknown query file" },
205 "...": {},
206 "query.json": {
207 "requests": [ {}, {}, {} ],
208 "responses": [
209 { "kind": "<kind>",
210 "version": { "major": 1, "minor": 0 },
211 "jsonFile": "<file>" },
212 { "error": "unknown query file" },
213 { "...": {} }
214 ],
215 "client": {}
216 }
217 }
218 }
219 }
220 The members are:
222 cmake A JSON object containing information about the instance of CMake
224 that generated the reply. It contains members:
225 version
227 A JSON object specifying the version of CMake with mem‐
228 bers:
229 major, minor, patch
231 Integer values specifying the major, minor, and
232 patch version components.
233 suffix A string specifying the version suffix, if any,
235 e.g. g0abc3.
236 string A string specifying the full version in the format
238 <major>.<minor>.<patch>[-<suffix>].
239 isDirty
241 A boolean indicating whether the version was built
242 from a version controlled source tree with local
243 modifications.
244 paths A JSON object specifying paths to things that come with
246 CMake. It has members for cmake, ctest, and cpack whose
247 values are JSON strings specifying the absolute path to
248 each tool, represented with forward slashes. It also has
249 a root member for the absolute path to the directory con‐
250 taining CMake resources like the Modules/ directory (see
251 CMAKE_ROOT).
252 generator
254 A JSON object describing the CMake generator used for the
255 build. It has members:
256 multiConfig
258 A boolean specifying whether the generator sup‐
259 ports multiple output configurations.
260 name A string specifying the name of the generator.
262 platform
264 If the generator supports CMAKE_GENERATOR_PLAT‐
265 FORM, this is a string specifying the generator
266 platform name.
267 objects
269 A JSON array listing all versions of all Object Kinds generated
270 as part of the reply. Each array entry is a v1 Reply File Ref‐
271 erence.
272 reply A JSON object mirroring the content of the query/ directory that
274 CMake loaded to produce the reply. The members are of the form
275 <kind>-v<major>
277 A member of this form appears for each of the v1 Shared
278 Stateless Query Files that CMake recognized as a request
279 for object kind <kind> with major version <major>. The
280 value is a v1 Reply File Reference to the corresponding
281 reply file for that object kind and version.
282 <unknown>
284 A member of this form appears for each of the v1 Shared
285 Stateless Query Files that CMake did not recognize. The
286 value is a JSON object with a single error member con‐
287 taining a string with an error message indicating that
288 the query file is unknown.
289 client-<client>
291 A member of this form appears for each client-owned di‐
292 rectory holding v1 Client Stateless Query Files. The
293 value is a JSON object mirroring the content of the
294 query/client-<client>/ directory. The members are of the
295 form:
296 <kind>-v<major>
298 A member of this form appears for each of the v1
299 Client Stateless Query Files that CMake recognized
300 as a request for object kind <kind> with major
301 version <major>. The value is a v1 Reply File
302 Reference to the corresponding reply file for that
303 object kind and version.
304 <unknown>
306 A member of this form appears for each of the v1
307 Client Stateless Query Files that CMake did not
308 recognize. The value is a JSON object with a sin‐
309 gle error member containing a string with an error
310 message indicating that the query file is unknown.
311 query.json
313 This member appears for clients using v1 Client
314 Stateful Query Files. If the query.json file
315 failed to read or parse as a JSON object, this
316 member is a JSON object with a single error member
317 containing a string with an error message. Other‐
318 wise, this member is a JSON object mirroring the
319 content of the query.json file. The members are:
320 client A copy of the query.json file client mem‐
322 ber, if it exists.
323 requests
325 A copy of the query.json file requests mem‐
326 ber, if it exists.
327 responses
329 If the query.json file requests member is
330 missing or invalid, this member is a JSON
331 object with a single error member contain‐
332 ing a string with an error message. Other‐
333 wise, this member contains a JSON array
334 with a response for each entry of the re‐
335 quests array, in the same order. Each re‐
336 sponse is
337 • a JSON object with a single error member
339 containing a string with an error mes‐
340 sage, or
341 • a v1 Reply File Reference to the corre‐
343 sponding reply file for the requested ob‐
344 ject kind and selected version.
345 After reading the reply index file, clients may read the other v1 Reply
347 Files it references.
348 v1 Reply File Reference
350 The reply index file represents each reference to another reply file
351 using a JSON object with members:
352 kind A string specifying one of the Object Kinds.
354 version
356 A JSON object with members major and minor specifying integer
357 version components of the object kind.
358 jsonFile
360 A JSON string specifying a path relative to the reply index file
361 to another JSON file containing the object.
362 v1 Reply Files
364 Reply files containing specific Object Kinds are written by CMake. The
365 names of these files are unspecified and must not be interpreted by
366 clients. Clients must first read the v1 Reply Index File and and fol‐
367 low references to the names of the desired response objects.
368 Reply files (including the index file) will never be replaced by files
370 of the same name but different content. This allows a client to read
371 the files concurrently with a running CMake that may generate a new re‐
372 ply. However, after generating a new reply CMake will attempt to re‐
373 move reply files from previous runs that it did not just write. If a
374 client attempts to read a reply file referenced by the index but finds
375 the file missing, that means a concurrent CMake has generated a new re‐
376 ply. The client may simply start again by reading the new reply index
377 file.
378
380 The CMake file-based API reports semantic information about the build
381 system using the following kinds of JSON objects. Each kind of object
382 is versioned independently using semantic versioning with major and mi‐
383 nor components. Every kind of object has the form:
384 {
386 "kind": "<kind>",
387 "version": { "major": 1, "minor": 0 },
388 "...": {}
389 }
390 The kind member is a string specifying the object kind name. The ver‐
392 sion member is a JSON object with major and minor members specifying
393 integer components of the object kind's version. Additional top-level
394 members are specific to each object kind.
395 Object Kind codemodel
397 The codemodel object kind describes the build system structure as mod‐
398 eled by CMake.
399 There is only one codemodel object major version, version 2. Version 1
401 does not exist to avoid confusion with that from cmake-server(7) mode.
402 codemodel version 2
404 codemodel object version 2 is a JSON object:
405 {
407 "kind": "codemodel",
408 "version": { "major": 2, "minor": 2 },
409 "paths": {
410 "source": "/path/to/top-level-source-dir",
411 "build": "/path/to/top-level-build-dir"
412 },
413 "configurations": [
414 {
415 "name": "Debug",
416 "directories": [
417 {
418 "source": ".",
419 "build": ".",
420 "childIndexes": [ 1 ],
421 "projectIndex": 0,
422 "targetIndexes": [ 0 ],
423 "hasInstallRule": true,
424 "minimumCMakeVersion": {
425 "string": "3.14"
426 }
427 },
428 {
429 "source": "sub",
430 "build": "sub",
431 "parentIndex": 0,
432 "projectIndex": 0,
433 "targetIndexes": [ 1 ],
434 "minimumCMakeVersion": {
435 "string": "3.14"
436 }
437 }
438 ],
439 "projects": [
440 {
441 "name": "MyProject",
442 "directoryIndexes": [ 0, 1 ],
443 "targetIndexes": [ 0, 1 ]
444 }
445 ],
446 "targets": [
447 {
448 "name": "MyExecutable",
449 "directoryIndex": 0,
450 "projectIndex": 0,
451 "jsonFile": "<file>"
452 },
453 {
454 "name": "MyLibrary",
455 "directoryIndex": 1,
456 "projectIndex": 0,
457 "jsonFile": "<file>"
458 }
459 ]
460 }
461 ]
462 }
463 The members specific to codemodel objects are:
465 paths A JSON object containing members:
467 source A string specifying the absolute path to the top-level
469 source directory, represented with forward slashes.
470 build A string specifying the absolute path to the top-level
472 build directory, represented with forward slashes.
473 configurations
475 A JSON array of entries corresponding to available build config‐
476 urations. On single-configuration generators there is one entry
477 for the value of the CMAKE_BUILD_TYPE variable. For multi-con‐
478 figuration generators there is an entry for each configuration
479 listed in the CMAKE_CONFIGURATION_TYPES variable. Each entry is
480 a JSON object containing members:
481 name A string specifying the name of the configuration, e.g.
483 Debug.
484 directories
486 A JSON array of entries each corresponding to a build
487 system directory whose source directory contains a CMake‐
488 Lists.txt file. The first entry corresponds to the
489 top-level directory. Each entry is a JSON object con‐
490 taining members:
491 source A string specifying the path to the source direc‐
493 tory, represented with forward slashes. If the
494 directory is inside the top-level source directory
495 then the path is specified relative to that direc‐
496 tory (with . for the top-level source directory
497 itself). Otherwise the path is absolute.
498 build A string specifying the path to the build direc‐
500 tory, represented with forward slashes. If the
501 directory is inside the top-level build directory
502 then the path is specified relative to that direc‐
503 tory (with . for the top-level build directory it‐
504 self). Otherwise the path is absolute.
505 parentIndex
507 Optional member that is present when the directory
508 is not top-level. The value is an unsigned inte‐
509 ger 0-based index of another entry in the main di‐
510 rectories array that corresponds to the parent di‐
511 rectory that added this directory as a subdirec‐
512 tory.
513 childIndexes
515 Optional member that is present when the directory
516 has subdirectories. The value is a JSON array of
517 entries corresponding to child directories created
518 by the add_subdirectory() or subdirs() command.
519 Each entry is an unsigned integer 0-based index of
520 another entry in the main directories array.
521 projectIndex
523 An unsigned integer 0-based index into the main
524 projects array indicating the build system project
525 to which the this directory belongs.
526 targetIndexes
528 Optional member that is present when the directory
529 itself has targets, excluding those belonging to
530 subdirectories. The value is a JSON array of en‐
531 tries corresponding to the targets. Each entry is
532 an unsigned integer 0-based index into the main
533 targets array.
534 minimumCMakeVersion
536 Optional member present when a minimum required
537 version of CMake is known for the directory. This
538 is the <min> version given to the most local call
539 to the cmake_minimum_required(VERSION) command in
540 the directory itself or one of its ancestors. The
541 value is a JSON object with one member:
542 string A string specifying the minimum required
544 version in the format:
545 <major>.<minor>[.<patch>[.<tweak>]][<suffix>]
547 Each component is an unsigned integer and
549 the suffix may be an arbitrary string.
550 hasInstallRule
552 Optional member that is present with boolean value
553 true when the directory or one of its subdirecto‐
554 ries contains any install() rules, i.e. whether a
555 make install or equivalent rule is available.
556 projects
558 A JSON array of entries corresponding to the top-level
559 project and sub-projects defined in the build system.
560 Each (sub-)project corresponds to a source directory
561 whose CMakeLists.txt file calls the project() command
562 with a project name different from its parent directory.
563 The first entry corresponds to the top-level project.
564 Each entry is a JSON object containing members:
566 name A string specifying the name given to the
568 project() command.
569 parentIndex
571 Optional member that is present when the project
572 is not top-level. The value is an unsigned inte‐
573 ger 0-based index of another entry in the main
574 projects array that corresponds to the parent
575 project that added this project as a sub-project.
576 childIndexes
578 Optional member that is present when the project
579 has sub-projects. The value is a JSON array of
580 entries corresponding to the sub-projects. Each
581 entry is an unsigned integer 0-based index of an‐
582 other entry in the main projects array.
583 directoryIndexes
585 A JSON array of entries corresponding to build
586 system directories that are part of the project.
587 The first entry corresponds to the top-level di‐
588 rectory of the project. Each entry is an unsigned
589 integer 0-based index into the main directories
590 array.
591 targetIndexes
593 Optional member that is present when the project
594 itself has targets, excluding those belonging to
595 sub-projects. The value is a JSON array of en‐
596 tries corresponding to the targets. Each entry is
597 an unsigned integer 0-based index into the main
598 targets array.
599 targets
601 A JSON array of entries corresponding to the build system
602 targets. Such targets are created by calls to add_exe‐
603 cutable(), add_library(), and add_custom_target(), ex‐
604 cluding imported targets and interface libraries (which
605 do not generate any build rules). Each entry is a JSON
606 object containing members:
607 name A string specifying the target name.
609 id A string uniquely identifying the target. This
611 matches the id field in the file referenced by
612 jsonFile.
613 directoryIndex
615 An unsigned integer 0-based index into the main
616 directories array indicating the build system di‐
617 rectory in which the target is defined.
618 projectIndex
620 An unsigned integer 0-based index into the main
621 projects array indicating the build system project
622 in which the target is defined.
623 jsonFile
625 A JSON string specifying a path relative to the
626 codemodel file to another JSON file containing a
627 "codemodel" version 2 "target" object.
628 codemodel version 2 target object
630 A codemodel "target" object is referenced by a "codemodel" version 2
631 object's targets array. Each "target" object is a JSON object with
632 members:
633 name A string specifying the logical name of the target.
635 id A string uniquely identifying the target. The format is unspec‐
637 ified and should not be interpreted by clients.
638 type A string specifying the type of the target. The value is one of
640 EXECUTABLE, STATIC_LIBRARY, SHARED_LIBRARY, MODULE_LIBRARY, OB‐
641 JECT_LIBRARY, INTERFACE_LIBRARY, or UTILITY.
642 backtrace
644 Optional member that is present when a CMake language backtrace
645 to the command in the source code that created the target is
646 available. The value is an unsigned integer 0-based index into
647 the backtraceGraph member's nodes array.
648 folder Optional member that is present when the FOLDER target property
650 is set. The value is a JSON object with one member:
651 name A string specifying the name of the target folder.
653 paths A JSON object containing members:
655 source A string specifying the path to the target's source di‐
657 rectory, represented with forward slashes. If the direc‐
658 tory is inside the top-level source directory then the
659 path is specified relative to that directory (with . for
660 the top-level source directory itself). Otherwise the
661 path is absolute.
662 build A string specifying the path to the target's build direc‐
664 tory, represented with forward slashes. If the directory
665 is inside the top-level build directory then the path is
666 specified relative to that directory (with . for the
667 top-level build directory itself). Otherwise the path is
668 absolute.
669 nameOnDisk
671 Optional member that is present for executable and library tar‐
672 gets that are linked or archived into a single primary artifact.
673 The value is a string specifying the file name of that artifact
674 on disk.
675 artifacts
677 Optional member that is present for executable and library tar‐
678 gets that produce artifacts on disk meant for consumption by de‐
679 pendents. The value is a JSON array of entries corresponding to
680 the artifacts. Each entry is a JSON object containing one mem‐
681 ber:
682 path A string specifying the path to the file on disk, repre‐
684 sented with forward slashes. If the file is inside the
685 top-level build directory then the path is specified rel‐
686 ative to that directory. Otherwise the path is absolute.
687 isGeneratorProvided
689 Optional member that is present with boolean value true if the
690 target is provided by CMake's build system generator rather than
691 by a command in the source code.
692 install
694 Optional member that is present when the target has an install()
695 rule. The value is a JSON object with members:
696 prefix A JSON object specifying the installation prefix. It has
698 one member:
699 path A string specifying the value of CMAKE_IN‐
701 STALL_PREFIX.
702 destinations
704 A JSON array of entries specifying an install destination
705 path. Each entry is a JSON object with members:
706 path A string specifying the install destination path.
708 The path may be absolute or relative to the in‐
709 stall prefix.
710 backtrace
712 Optional member that is present when a CMake lan‐
713 guage backtrace to the install() command invoca‐
714 tion that specified this destination is available.
715 The value is an unsigned integer 0-based index
716 into the backtraceGraph member's nodes array.
717 link Optional member that is present for executables and shared li‐
719 brary targets that link into a runtime binary. The value is a
720 JSON object with members describing the link step:
721 language
723 A string specifying the language (e.g. C, CXX, Fortran)
724 of the toolchain is used to invoke the linker.
725 commandFragments
727 Optional member that is present when fragments of the
728 link command line invocation are available. The value is
729 a JSON array of entries specifying ordered fragments.
730 Each entry is a JSON object with members:
731 fragment
733 A string specifying a fragment of the link command
734 line invocation. The value is encoded in the
735 build system's native shell format.
736 role A string specifying the role of the fragment's
738 content:
739 • flags: link flags.
741 • libraries: link library file paths or flags.
743 • libraryPath: library search path flags.
745 • frameworkPath: macOS framework search path
747 flags.
748 lto Optional member that is present with boolean value true
750 when link-time optimization (a.k.a. interprocedural opti‐
751 mization or link-time code generation) is enabled.
752 sysroot
754 Optional member that is present when the CMAKE_SYS‐
755 ROOT_LINK or CMAKE_SYSROOT variable is defined. The
756 value is a JSON object with one member:
757 path A string specifying the absolute path to the sys‐
759 root, represented with forward slashes.
760 archive
762 Optional member that is present for static library targets. The
763 value is a JSON object with members describing the archive step:
764 commandFragments
766 Optional member that is present when fragments of the
767 archiver command line invocation are available. The
768 value is a JSON array of entries specifying the frag‐
769 ments. Each entry is a JSON object with members:
770 fragment
772 A string specifying a fragment of the archiver
773 command line invocation. The value is encoded in
774 the build system's native shell format.
775 role A string specifying the role of the fragment's
777 content:
778 • flags: archiver flags.
780 lto Optional member that is present with boolean value true
782 when link-time optimization (a.k.a. interprocedural opti‐
783 mization or link-time code generation) is enabled.
784 dependencies
786 Optional member that is present when the target depends on other
787 targets. The value is a JSON array of entries corresponding to
788 the dependencies. Each entry is a JSON object with members:
789 id A string uniquely identifying the target on which this
791 target depends. This matches the main id member of the
792 other target.
793 backtrace
795 Optional member that is present when a CMake language
796 backtrace to the add_dependencies(), target_link_li‐
797 braries(), or other command invocation that created this
798 dependency is available. The value is an unsigned inte‐
799 ger 0-based index into the backtraceGraph member's nodes
800 array.
801 sources
803 A JSON array of entries corresponding to the target's source
804 files. Each entry is a JSON object with members:
805 path A string specifying the path to the source file on disk,
807 represented with forward slashes. If the file is inside
808 the top-level source directory then the path is specified
809 relative to that directory. Otherwise the path is abso‐
810 lute.
811 compileGroupIndex
813 Optional member that is present when the source is com‐
814 piled. The value is an unsigned integer 0-based index
815 into the compileGroups array.
816 sourceGroupIndex
818 Optional member that is present when the source is part
819 of a source group either via the source_group() command
820 or by default. The value is an unsigned integer 0-based
821 index into the sourceGroups array.
822 isGenerated
824 Optional member that is present with boolean value true
825 if the source is GENERATED.
826 backtrace
828 Optional member that is present when a CMake language
829 backtrace to the target_sources(), add_executable(),
830 add_library(), add_custom_target(), or other command in‐
831 vocation that added this source to the target is avail‐
832 able. The value is an unsigned integer 0-based index
833 into the backtraceGraph member's nodes array.
834 sourceGroups
836 Optional member that is present when sources are grouped to‐
837 gether by the source_group() command or by default. The value
838 is a JSON array of entries corresponding to the groups. Each
839 entry is a JSON object with members:
840 name A string specifying the name of the source group.
842 sourceIndexes
844 A JSON array listing the sources belonging to the group.
845 Each entry is an unsigned integer 0-based index into the
846 main sources array for the target.
847 compileGroups
849 Optional member that is present when the target has sources that
850 compile. The value is a JSON array of entries corresponding to
851 groups of sources that all compile with the same settings. Each
852 entry is a JSON object with members:
853 sourceIndexes
855 A JSON array listing the sources belonging to the group.
856 Each entry is an unsigned integer 0-based index into the
857 main sources array for the target.
858 language
860 A string specifying the language (e.g. C, CXX, Fortran)
861 of the toolchain is used to compile the source file.
862 languageStandard
864 Optional member that is present when the language stan‐
865 dard is set explicitly (e.g. via CXX_STANDARD) or implic‐
866 itly by compile features. Each entry is a JSON object
867 with two members:
868 backtraces
870 Optional member that is present when a CMake lan‐
871 guage backtrace to the <LANG>_STANDARD setting is
872 available. If the language standard was set im‐
873 plicitly by compile features those are used as the
874 backtrace(s). It's possible for multiple compile
875 features to require the same language standard so
876 there could be multiple backtraces. The value is a
877 JSON array with each entry being an unsigned inte‐
878 ger 0-based index into the backtraceGraph member's
879 nodes array.
880 standard
882 String representing the language standard.
883 This field was added in codemodel version 2.2.
885 compileCommandFragments
887 Optional member that is present when fragments of the
888 compiler command line invocation are available. The
889 value is a JSON array of entries specifying ordered frag‐
890 ments. Each entry is a JSON object with one member:
891 fragment
893 A string specifying a fragment of the compile com‐
894 mand line invocation. The value is encoded in the
895 build system's native shell format.
896 includes
898 Optional member that is present when there are include
899 directories. The value is a JSON array with an entry for
900 each directory. Each entry is a JSON object with mem‐
901 bers:
902 path A string specifying the path to the include direc‐
904 tory, represented with forward slashes.
905 isSystem
907 Optional member that is present with boolean value
908 true if the include directory is marked as a sys‐
909 tem include directory.
910 backtrace
912 Optional member that is present when a CMake lan‐
913 guage backtrace to the target_include_directo‐
914 ries() or other command invocation that added this
915 include directory is available. The value is an
916 unsigned integer 0-based index into the backtrace‐
917 Graph member's nodes array.
918 precompileHeaders
920 Optional member that is present when target_precom‐
921 pile_headers() or other command invocations set PRECOM‐
922 PILE_HEADERS on the target. The value is a JSON array
923 with an entry for each header. Each entry is a JSON ob‐
924 ject with members:
925 header Full path to the precompile header file.
927 backtrace
929 Optional member that is present when a CMake lan‐
930 guage backtrace to the target_precompile_headers()
931 or other command invocation that added this pre‐
932 compiled header is available. The value is an un‐
933 signed integer 0-based index into the backtrace‐
934 Graph member's nodes array.
935 This field was added in codemodel version 2.1.
937 defines
939 Optional member that is present when there are preproces‐
940 sor definitions. The value is a JSON array with an entry
941 for each definition. Each entry is a JSON object with
942 members:
943 define A string specifying the preprocessor definition in
945 the format <name>[=<value>], e.g. DEF or DEF=1.
946 backtrace
948 Optional member that is present when a CMake lan‐
949 guage backtrace to the target_compile_defini‐
950 tions() or other command invocation that added
951 this preprocessor definition is available. The
952 value is an unsigned integer 0-based index into
953 the backtraceGraph member's nodes array.
954 sysroot
956 Optional member that is present when the CMAKE_SYS‐
957 ROOT_COMPILE or CMAKE_SYSROOT variable is defined. The
958 value is a JSON object with one member:
959 path A string specifying the absolute path to the sys‐
961 root, represented with forward slashes.
962 backtraceGraph
964 A JSON object describing the graph of backtraces whose nodes are
965 referenced from backtrace members elsewhere. The members are:
966 nodes A JSON array listing nodes in the backtrace graph. Each
968 entry is a JSON object with members:
969 file An unsigned integer 0-based index into the back‐
971 trace files array.
972 line An optional member present when the node repre‐
974 sents a line within the file. The value is an un‐
975 signed integer 1-based line number.
976 command
978 An optional member present when the node repre‐
979 sents a command invocation within the file. The
980 value is an unsigned integer 0-based index into
981 the backtrace commands array.
982 parent An optional member present when the node is not
984 the bottom of the call stack. The value is an un‐
985 signed integer 0-based index of another entry in
986 the backtrace nodes array.
987 commands
989 A JSON array listing command names referenced by back‐
990 trace nodes. Each entry is a string specifying a command
991 name.
992 files A JSON array listing CMake language files referenced by
994 backtrace nodes. Each entry is a string specifying the
995 path to a file, represented with forward slashes. If the
996 file is inside the top-level source directory then the
997 path is specified relative to that directory. Otherwise
998 the path is absolute.
999 Object Kind cache
1001 The cache object kind lists cache entries. These are the CMake Lan‐
1002 guage Variables stored in the persistent cache (CMakeCache.txt) for the
1003 build tree.
1004 There is only one cache object major version, version 2. Version 1
1006 does not exist to avoid confusion with that from cmake-server(7) mode.
1007 cache version 2
1009 cache object version 2 is a JSON object:
1010 {
1012 "kind": "cache",
1013 "version": { "major": 2, "minor": 0 },
1014 "entries": [
1015 {
1016 "name": "BUILD_SHARED_LIBS",
1017 "value": "ON",
1018 "type": "BOOL",
1019 "properties": [
1020 {
1021 "name": "HELPSTRING",
1022 "value": "Build shared libraries"
1023 }
1024 ]
1025 },
1026 {
1027 "name": "CMAKE_GENERATOR",
1028 "value": "Unix Makefiles",
1029 "type": "INTERNAL",
1030 "properties": [
1031 {
1032 "name": "HELPSTRING",
1033 "value": "Name of generator."
1034 }
1035 ]
1036 }
1037 ]
1038 }
1039 The members specific to cache objects are:
1041 entries
1043 A JSON array whose entries are each a JSON object specifying a
1044 cache entry. The members of each entry are:
1045 name A string specifying the name of the entry.
1047 value A string specifying the value of the entry.
1049 type A string specifying the type of the entry used by
1051 cmake-gui(1) to choose a widget for editing.
1052 properties
1054 A JSON array of entries specifying associated cache entry
1055 properties. Each entry is a JSON object containing mem‐
1056 bers:
1057 name A string specifying the name of the cache entry
1059 property.
1060 value A string specifying the value of the cache entry
1062 property.
1063 Object Kind cmakeFiles
1065 The cmakeFiles object kind lists files used by CMake while configuring
1066 and generating the build system. These include the CMakeLists.txt
1067 files as well as included .cmake files.
1068 There is only one cmakeFiles object major version, version 1.
1070 cmakeFiles version 1
1072 cmakeFiles object version 1 is a JSON object:
1073 {
1075 "kind": "cmakeFiles",
1076 "version": { "major": 1, "minor": 0 },
1077 "paths": {
1078 "build": "/path/to/top-level-build-dir",
1079 "source": "/path/to/top-level-source-dir"
1080 },
1081 "inputs": [
1082 {
1083 "path": "CMakeLists.txt"
1084 },
1085 {
1086 "isGenerated": true,
1087 "path": "/path/to/top-level-build-dir/.../CMakeSystem.cmake"
1088 },
1089 {
1090 "isExternal": true,
1091 "path": "/path/to/external/third-party/module.cmake"
1092 },
1093 {
1094 "isCMake": true,
1095 "isExternal": true,
1096 "path": "/path/to/cmake/Modules/CMakeGenericSystem.cmake"
1097 }
1098 ]
1099 }
1100 The members specific to cmakeFiles objects are:
1102 paths A JSON object containing members:
1104 source A string specifying the absolute path to the top-level
1106 source directory, represented with forward slashes.
1107 build A string specifying the absolute path to the top-level
1109 build directory, represented with forward slashes.
1110 inputs A JSON array whose entries are each a JSON object specifying an
1112 input file used by CMake when configuring and generating the
1113 build system. The members of each entry are:
1114 path A string specifying the path to an input file to CMake,
1116 represented with forward slashes. If the file is inside
1117 the top-level source directory then the path is specified
1118 relative to that directory. Otherwise the path is abso‐
1119 lute.
1120 isGenerated
1122 Optional member that is present with boolean value true
1123 if the path specifies a file that is under the top-level
1124 build directory and the build is out-of-source. This
1125 member is not available on in-source builds.
1126 isExternal
1128 Optional member that is present with boolean value true
1129 if the path specifies a file that is not under the
1130 top-level source or build directories.
1131 isCMake
1133 Optional member that is present with boolean value true
1134 if the path specifies a file in the CMake installation.
1135 Object Kind toolchains
1137 The toolchains object kind lists properties of the toolchains used dur‐
1138 ing the build. These include the language, compiler path, ID, and ver‐
1139 sion.
1140 There is only one toolchains object major version, version 1.
1142 toolchains version 1
1144 toolchains object version 1 is a JSON object:
1145 {
1147 "kind": "toolchains",
1148 "version": { "major": 1, "minor": 0 },
1149 "toolchains": [
1150 {
1151 "language": "C",
1152 "compiler": {
1153 "path": "/usr/bin/cc",
1154 "id": "GNU",
1155 "version": "9.3.0",
1156 "implicit": {
1157 "includeDirectories": [
1158 "/usr/lib/gcc/x86_64-linux-gnu/9/include",
1159 "/usr/local/include",
1160 "/usr/include/x86_64-linux-gnu",
1161 "/usr/include"
1162 ],
1163 "linkDirectories": [
1164 "/usr/lib/gcc/x86_64-linux-gnu/9",
1165 "/usr/lib/x86_64-linux-gnu",
1166 "/usr/lib",
1167 "/lib/x86_64-linux-gnu",
1168 "/lib"
1169 ],
1170 "linkFrameworkDirectories": [],
1171 "linkLibraries": [ "gcc", "gcc_s", "c", "gcc", "gcc_s" ]
1172 }
1173 },
1174 "sourceFileExtensions": [ "c", "m" ]
1175 },
1176 {
1177 "language": "CXX",
1178 "compiler": {
1179 "path": "/usr/bin/c++",
1180 "id": "GNU",
1181 "version": "9.3.0",
1182 "implicit": {
1183 "includeDirectories": [
1184 "/usr/include/c++/9",
1185 "/usr/include/x86_64-linux-gnu/c++/9",
1186 "/usr/include/c++/9/backward",
1187 "/usr/lib/gcc/x86_64-linux-gnu/9/include",
1188 "/usr/local/include",
1189 "/usr/include/x86_64-linux-gnu",
1190 "/usr/include"
1191 ],
1192 "linkDirectories": [
1193 "/usr/lib/gcc/x86_64-linux-gnu/9",
1194 "/usr/lib/x86_64-linux-gnu",
1195 "/usr/lib",
1196 "/lib/x86_64-linux-gnu",
1197 "/lib"
1198 ],
1199 "linkFrameworkDirectories": [],
1200 "linkLibraries": [
1201 "stdc++", "m", "gcc_s", "gcc", "c", "gcc_s", "gcc"
1202 ]
1203 }
1204 },
1205 "sourceFileExtensions": [
1206 "C", "M", "c++", "cc", "cpp", "cxx", "mm", "CPP"
1207 ]
1208 }
1209 ]
1210 }
1211 The members specific to toolchains objects are:
1213 toolchains
1215 A JSON array whose entries are each a JSON object specifying a
1216 toolchain associated with a particular language. The members of
1217 each entry are:
1218 language
1220 A JSON string specifying the toolchain language, like C
1221 or CXX. Language names are the same as langauge names
1222 that can be passed to the project() command. Because
1223 CMake only supports a single toolchain per language, this
1224 field can be used as a key.
1225 compiler
1227 A JSON object containing members:
1228 path Optional member that is present when the
1230 CMAKE_<LANG>_COMPILER variable is defined for the
1231 current language. Its value is a JSON string hold‐
1232 ing the path to the compiler.
1233 id Optional member that is present when the
1235 CMAKE_<LANG>_COMPILER_ID variable is defined for
1236 the current language. Its value is a JSON string
1237 holding the ID (GNU, MSVC, etc.) of the compiler.
1238 version
1240 Optional member that is present when the
1241 CMAKE_<LANG>_COMPILER_VERSION variable is defined
1242 for the current language. Its value is a JSON
1243 string holding the version of the compiler.
1244 target Optional member that is present when the
1246 CMAKE_<LANG>_COMPILER_TARGET variable is defined
1247 for the current language. Its value is a JSON
1248 string holding the cross-compiling target of the
1249 compiler.
1250 implicit
1252 A JSON object containing members:
1253 includeDirectories
1255 Optional member that is present when the
1256 CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES
1257 variable is defined for the current lan‐
1258 guage. Its value is a JSON array of JSON
1259 strings where each string holds a path to
1260 an implicit include directory for the com‐
1261 piler.
1262 linkDirectories
1264 Optional member that is present when the
1265 CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES
1266 variable is defined for the current lan‐
1267 guage. Its value is a JSON array of JSON
1268 strings where each string holds a path to
1269 an implicit link directory for the com‐
1270 piler.
1271 linkFrameworkDirectories
1273 Optional member that is present when the
1274 CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIREC‐
1275 TORIES variable is defined for the current
1276 language. Its value is a JSON array of JSON
1277 strings where each string holds a path to
1278 an implicit link framework directory for
1279 the compiler.
1280 linkLibraries
1282 Optional member that is present when the
1283 CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES vari‐
1284 able is defined for the current language.
1285 Its value is a JSON array of JSON strings
1286 where each string holds a path to an im‐
1287 plicit link library for the compiler.
1288 sourceFileExtensions
1290 Optional member that is present when the
1291 CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS variable is defined
1292 for the current language. Its value is a JSON array of
1293 JSON strings where each each string holds a file exten‐
1294 sion (without the leading dot) for the language.
1295
1297 2000-2021 Kitware, Inc. and Contributors
12983.20.3 May 30, 2021 CMAKE-FILE-API(7)