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 "jsonFile": "<file>"
428 },
429 {
430 "source": "sub",
431 "build": "sub",
432 "parentIndex": 0,
433 "projectIndex": 0,
434 "targetIndexes": [ 1 ],
435 "minimumCMakeVersion": {
436 "string": "3.14"
437 },
438 "jsonFile": "<file>"
439 }
440 ],
441 "projects": [
442 {
443 "name": "MyProject",
444 "directoryIndexes": [ 0, 1 ],
445 "targetIndexes": [ 0, 1 ]
446 }
447 ],
448 "targets": [
449 {
450 "name": "MyExecutable",
451 "directoryIndex": 0,
452 "projectIndex": 0,
453 "jsonFile": "<file>"
454 },
455 {
456 "name": "MyLibrary",
457 "directoryIndex": 1,
458 "projectIndex": 0,
459 "jsonFile": "<file>"
460 }
461 ]
462 }
463 ]
464 }
465 The members specific to codemodel objects are:
467 paths A JSON object containing members:
469 source A string specifying the absolute path to the top-level
471 source directory, represented with forward slashes.
472 build A string specifying the absolute path to the top-level
474 build directory, represented with forward slashes.
475 configurations
477 A JSON array of entries corresponding to available build config‐
478 urations. On single-configuration generators there is one entry
479 for the value of the CMAKE_BUILD_TYPE variable. For multi-con‐
480 figuration generators there is an entry for each configuration
481 listed in the CMAKE_CONFIGURATION_TYPES variable. Each entry is
482 a JSON object containing members:
483 name A string specifying the name of the configuration, e.g.
485 Debug.
486 directories
488 A JSON array of entries each corresponding to a build
489 system directory whose source directory contains a CMake‐
490 Lists.txt file. The first entry corresponds to the
491 top-level directory. Each entry is a JSON object con‐
492 taining members:
493 source A string specifying the path to the source direc‐
495 tory, represented with forward slashes. If the
496 directory is inside the top-level source directory
497 then the path is specified relative to that direc‐
498 tory (with . for the top-level source directory
499 itself). Otherwise the path is absolute.
500 build A string specifying the path to the build direc‐
502 tory, represented with forward slashes. If the
503 directory is inside the top-level build directory
504 then the path is specified relative to that direc‐
505 tory (with . for the top-level build directory it‐
506 self). Otherwise the path is absolute.
507 parentIndex
509 Optional member that is present when the directory
510 is not top-level. The value is an unsigned inte‐
511 ger 0-based index of another entry in the main di‐
512 rectories array that corresponds to the parent di‐
513 rectory that added this directory as a subdirec‐
514 tory.
515 childIndexes
517 Optional member that is present when the directory
518 has subdirectories. The value is a JSON array of
519 entries corresponding to child directories created
520 by the add_subdirectory() or subdirs() command.
521 Each entry is an unsigned integer 0-based index of
522 another entry in the main directories array.
523 projectIndex
525 An unsigned integer 0-based index into the main
526 projects array indicating the build system project
527 to which the this directory belongs.
528 targetIndexes
530 Optional member that is present when the directory
531 itself has targets, excluding those belonging to
532 subdirectories. The value is a JSON array of en‐
533 tries corresponding to the targets. Each entry is
534 an unsigned integer 0-based index into the main
535 targets array.
536 minimumCMakeVersion
538 Optional member present when a minimum required
539 version of CMake is known for the directory. This
540 is the <min> version given to the most local call
541 to the cmake_minimum_required(VERSION) command in
542 the directory itself or one of its ancestors. The
543 value is a JSON object with one member:
544 string A string specifying the minimum required
546 version in the format:
547 <major>.<minor>[.<patch>[.<tweak>]][<suffix>]
549 Each component is an unsigned integer and
551 the suffix may be an arbitrary string.
552 hasInstallRule
554 Optional member that is present with boolean value
555 true when the directory or one of its subdirecto‐
556 ries contains any install() rules, i.e. whether a
557 make install or equivalent rule is available.
558 jsonFile
560 A JSON string specifying a path relative to the
561 codemodel file to another JSON file containing a
562 "codemodel" version 2 "directory" object.
563 This field was added in codemodel version 2.3.
565 projects
567 A JSON array of entries corresponding to the top-level
568 project and sub-projects defined in the build system.
569 Each (sub-)project corresponds to a source directory
570 whose CMakeLists.txt file calls the project() command
571 with a project name different from its parent directory.
572 The first entry corresponds to the top-level project.
573 Each entry is a JSON object containing members:
575 name A string specifying the name given to the
577 project() command.
578 parentIndex
580 Optional member that is present when the project
581 is not top-level. The value is an unsigned inte‐
582 ger 0-based index of another entry in the main
583 projects array that corresponds to the parent
584 project that added this project as a sub-project.
585 childIndexes
587 Optional member that is present when the project
588 has sub-projects. The value is a JSON array of
589 entries corresponding to the sub-projects. Each
590 entry is an unsigned integer 0-based index of an‐
591 other entry in the main projects array.
592 directoryIndexes
594 A JSON array of entries corresponding to build
595 system directories that are part of the project.
596 The first entry corresponds to the top-level di‐
597 rectory of the project. Each entry is an unsigned
598 integer 0-based index into the main directories
599 array.
600 targetIndexes
602 Optional member that is present when the project
603 itself has targets, excluding those belonging to
604 sub-projects. The value is a JSON array of en‐
605 tries corresponding to the targets. Each entry is
606 an unsigned integer 0-based index into the main
607 targets array.
608 targets
610 A JSON array of entries corresponding to the build system
611 targets. Such targets are created by calls to add_exe‐
612 cutable(), add_library(), and add_custom_target(), ex‐
613 cluding imported targets and interface libraries (which
614 do not generate any build rules). Each entry is a JSON
615 object containing members:
616 name A string specifying the target name.
618 id A string uniquely identifying the target. This
620 matches the id field in the file referenced by
621 jsonFile.
622 directoryIndex
624 An unsigned integer 0-based index into the main
625 directories array indicating the build system di‐
626 rectory in which the target is defined.
627 projectIndex
629 An unsigned integer 0-based index into the main
630 projects array indicating the build system project
631 in which the target is defined.
632 jsonFile
634 A JSON string specifying a path relative to the
635 codemodel file to another JSON file containing a
636 "codemodel" version 2 "target" object.
637 codemodel version 2 directory object
639 A codemodel "directory" object is referenced by a "codemodel" version 2
640 object's directories array. Each "directory" object is a JSON object
641 with members:
642 paths A JSON object containing members:
644 source A string specifying the path to the source directory,
646 represented with forward slashes. If the directory is
647 inside the top-level source directory then the path is
648 specified relative to that directory (with . for the
649 top-level source directory itself). Otherwise the path
650 is absolute.
651 build A string specifying the path to the build directory, rep‐
653 resented with forward slashes. If the directory is in‐
654 side the top-level build directory then the path is spec‐
655 ified relative to that directory (with . for the
656 top-level build directory itself). Otherwise the path is
657 absolute.
658 installers
660 A JSON array of entries corresponding to install() rules. Each
661 entry is a JSON object containing members:
662 component
664 A string specifying the component selected by the corre‐
665 sponding install() command invocation.
666 destination
668 Optional member that is present for specific type values
669 below. The value is a string specifying the install des‐
670 tination path. The path may be absolute or relative to
671 the install prefix.
672 paths Optional member that is present for specific type values
674 below. The value is a JSON array of entries correspond‐
675 ing to the paths (files or directories) to be installed.
676 Each entry is one of:
677 • A string specifying the path from which a file or di‐
679 rectory is to be installed. The portion of the path
680 not preceded by a / also specifies the path (name) to
681 which the file or directory is to be installed under
682 the destination.
683 • A JSON object with members:
685 from A string specifying the path from which a file
687 or directory is to be installed.
688 to A string specifying the path to which the file
690 or directory is to be installed under the desti‐
691 nation.
692 In both cases the paths are represented with forward
694 slashes. If the "from" path is inside the top-level di‐
695 rectory documented by the corresponding type value, then
696 the path is specified relative to that directory. Other‐
697 wise the path is absolute.
698 type A string specifying the type of installation rule. The
700 value is one of the following, with some variants provid‐
701 ing additional members:
702 file An install(FILES) or install(PROGRAMS) call. The
704 destination and paths members are populated, with
705 paths under the top-level source directory ex‐
706 pressed relative to it. The isOptional member may
707 exist. This type has no additional members.
708 directory
710 An install(DIRECTORY) call. The destination and
711 paths members are populated, with paths under the
712 top-level source directory expressed relative to
713 it. The isOptional member may exist. This type
714 has no additional members.
715 target An install(TARGETS) call. The destination and
717 paths members are populated, with paths under the
718 top-level build directory expressed relative to
719 it. The isOptional member may exist. This type
720 has additional members targetId, targetIndex, tar‐
721 getIsImportLibrary, and targetInstallNamelink.
722 export An install(EXPORT) call. The destination and
724 paths members are populated, with paths under the
725 top-level build directory expressed relative to
726 it. The paths entries refer to files generated
727 automatically by CMake for installation, and their
728 actual values are considered private implementa‐
729 tion details. This type has additional members
730 exportName and exportTargets.
731 script An install(SCRIPT) call. This type has additional
733 member scriptFile.
734 code An install(CODE) call. This type has no addi‐
736 tional members.
737 importedRuntimeArtifacts
739 An install(IMPORTED_RUNTIME_ARTIFACTS) call. The
740 destination member is populated. The isOptional
741 member may exist. This type has no additional mem‐
742 bers.
743 runtimeDependencySet
745 An install(RUNTIME_DEPENDENCY_SET) call or an in‐
746 stall(TARGETS) call with RUNTIME_DEPENDENCIES. The
747 destination member is populated. This type has ad‐
748 ditional members runtimeDependencySetName and run‐
749 timeDependencySetType.
750 isExcludeFromAll
752 Optional member that is present with boolean value true
753 when install() is called with the EXCLUDE_FROM_ALL op‐
754 tion.
755 isForAllComponents
757 Optional member that is present with boolean value true
758 when install(SCRIPT|CODE) is called with the ALL_COMPO‐
759 NENTS option.
760 isOptional
762 Optional member that is present with boolean value true
763 when install() is called with the OPTIONAL option. This
764 is allowed when type is file, directory, or target.
765 targetId
767 Optional member that is present when type is target. The
768 value is a string uniquely identifying the target to be
769 installed. This matches the id member of the target in
770 the main "codemodel" object's targets array.
771 targetIndex
773 Optional member that is present when type is target. The
774 value is an unsigned integer 0-based index into the main
775 "codemodel" object's targets array for the target to be
776 installed.
777 targetIsImportLibrary
779 Optional member that is present when type is target and
780 the installer is for a Windows DLL import library file or
781 for an AIX linker import file. If present, it has bool‐
782 ean value true.
783 targetInstallNamelink
785 Optional member that is present when type is target and
786 the installer corresponds to a target that may use sym‐
787 bolic links to implement the VERSION and SOVERSION target
788 properties. The value is a string indicating how the in‐
789 staller is supposed to handle the symlinks: skip means
790 the installer should skip the symlinks and install only
791 the real file, and only means the installer should in‐
792 stall only the symlinks and not the real file. In all
793 cases the paths member lists what it actually installs.
794 exportName
796 Optional member that is present when type is export. The
797 value is a string specifying the name of the export.
798 exportTargets
800 Optional member that is present when type is export. The
801 value is a JSON array of entries corresponding to the
802 targets included in the export. Each entry is a JSON ob‐
803 ject with members:
804 id A string uniquely identifying the target. This
806 matches the id member of the target in the main
807 "codemodel" object's targets array.
808 index An unsigned integer 0-based index into the main
810 "codemodel" object's targets array for the target.
811 runtimeDependencySetName
813 Optional member that is present when type is runtimeDe‐
814 pendencySet and the installer was created by an in‐
815 stall(RUNTIME_DEPENDENCY_SET) call. The value is a string
816 specifying the name of the runtime dependency set that
817 was installed.
818 runtimeDependencySetType
820 Optional member that is present when type is runtimeDe‐
821 pendencySet. The value is a string with one of the fol‐
822 lowing values:
823 library
825 Indicates that this installer installs dependen‐
826 cies that are not macOS frameworks.
827 framework
829 Indicates that this installer installs dependen‐
830 cies that are macOS frameworks.
831 scriptFile
833 Optional member that is present when type is script. The
834 value is a string specifying the path to the script file
835 on disk, represented with forward slashes. If the file
836 is inside the top-level source directory then the path is
837 specified relative to that directory. Otherwise the path
838 is absolute.
839 backtrace
841 Optional member that is present when a CMake language
842 backtrace to the install() or other command invocation
843 that added this installer is available. The value is an
844 unsigned integer 0-based index into the backtraceGraph
845 member's nodes array.
846 backtraceGraph
848 A "codemodel" version 2 "backtrace graph" whose nodes are refer‐
849 enced from backtrace members elsewhere in this "directory" ob‐
850 ject.
851 codemodel version 2 target object
853 A codemodel "target" object is referenced by a "codemodel" version 2
854 object's targets array. Each "target" object is a JSON object with
855 members:
856 name A string specifying the logical name of the target.
858 id A string uniquely identifying the target. The format is unspec‐
860 ified and should not be interpreted by clients.
861 type A string specifying the type of the target. The value is one of
863 EXECUTABLE, STATIC_LIBRARY, SHARED_LIBRARY, MODULE_LIBRARY, OB‐
864 JECT_LIBRARY, INTERFACE_LIBRARY, or UTILITY.
865 backtrace
867 Optional member that is present when a CMake language backtrace
868 to the command in the source code that created the target is
869 available. The value is an unsigned integer 0-based index into
870 the backtraceGraph member's nodes array.
871 folder Optional member that is present when the FOLDER target property
873 is set. The value is a JSON object with one member:
874 name A string specifying the name of the target folder.
876 paths A JSON object containing members:
878 source A string specifying the path to the target's source di‐
880 rectory, represented with forward slashes. If the direc‐
881 tory is inside the top-level source directory then the
882 path is specified relative to that directory (with . for
883 the top-level source directory itself). Otherwise the
884 path is absolute.
885 build A string specifying the path to the target's build direc‐
887 tory, represented with forward slashes. If the directory
888 is inside the top-level build directory then the path is
889 specified relative to that directory (with . for the
890 top-level build directory itself). Otherwise the path is
891 absolute.
892 nameOnDisk
894 Optional member that is present for executable and library tar‐
895 gets that are linked or archived into a single primary artifact.
896 The value is a string specifying the file name of that artifact
897 on disk.
898 artifacts
900 Optional member that is present for executable and library tar‐
901 gets that produce artifacts on disk meant for consumption by de‐
902 pendents. The value is a JSON array of entries corresponding to
903 the artifacts. Each entry is a JSON object containing one mem‐
904 ber:
905 path A string specifying the path to the file on disk, repre‐
907 sented with forward slashes. If the file is inside the
908 top-level build directory then the path is specified rel‐
909 ative to that directory. Otherwise the path is absolute.
910 isGeneratorProvided
912 Optional member that is present with boolean value true if the
913 target is provided by CMake's build system generator rather than
914 by a command in the source code.
915 install
917 Optional member that is present when the target has an install()
918 rule. The value is a JSON object with members:
919 prefix A JSON object specifying the installation prefix. It has
921 one member:
922 path A string specifying the value of CMAKE_IN‐
924 STALL_PREFIX.
925 destinations
927 A JSON array of entries specifying an install destination
928 path. Each entry is a JSON object with members:
929 path A string specifying the install destination path.
931 The path may be absolute or relative to the in‐
932 stall prefix.
933 backtrace
935 Optional member that is present when a CMake lan‐
936 guage backtrace to the install() command invoca‐
937 tion that specified this destination is available.
938 The value is an unsigned integer 0-based index
939 into the backtraceGraph member's nodes array.
940 link Optional member that is present for executables and shared li‐
942 brary targets that link into a runtime binary. The value is a
943 JSON object with members describing the link step:
944 language
946 A string specifying the language (e.g. C, CXX, Fortran)
947 of the toolchain is used to invoke the linker.
948 commandFragments
950 Optional member that is present when fragments of the
951 link command line invocation are available. The value is
952 a JSON array of entries specifying ordered fragments.
953 Each entry is a JSON object with members:
954 fragment
956 A string specifying a fragment of the link command
957 line invocation. The value is encoded in the
958 build system's native shell format.
959 role A string specifying the role of the fragment's
961 content:
962 • flags: link flags.
964 • libraries: link library file paths or flags.
966 • libraryPath: library search path flags.
968 • frameworkPath: macOS framework search path
970 flags.
971 lto Optional member that is present with boolean value true
973 when link-time optimization (a.k.a. interprocedural opti‐
974 mization or link-time code generation) is enabled.
975 sysroot
977 Optional member that is present when the CMAKE_SYS‐
978 ROOT_LINK or CMAKE_SYSROOT variable is defined. The
979 value is a JSON object with one member:
980 path A string specifying the absolute path to the sys‐
982 root, represented with forward slashes.
983 archive
985 Optional member that is present for static library targets. The
986 value is a JSON object with members describing the archive step:
987 commandFragments
989 Optional member that is present when fragments of the
990 archiver command line invocation are available. The
991 value is a JSON array of entries specifying the frag‐
992 ments. Each entry is a JSON object with members:
993 fragment
995 A string specifying a fragment of the archiver
996 command line invocation. The value is encoded in
997 the build system's native shell format.
998 role A string specifying the role of the fragment's
1000 content:
1001 • flags: archiver flags.
1003 lto Optional member that is present with boolean value true
1005 when link-time optimization (a.k.a. interprocedural opti‐
1006 mization or link-time code generation) is enabled.
1007 dependencies
1009 Optional member that is present when the target depends on other
1010 targets. The value is a JSON array of entries corresponding to
1011 the dependencies. Each entry is a JSON object with members:
1012 id A string uniquely identifying the target on which this
1014 target depends. This matches the main id member of the
1015 other target.
1016 backtrace
1018 Optional member that is present when a CMake language
1019 backtrace to the add_dependencies(), target_link_li‐
1020 braries(), or other command invocation that created this
1021 dependency is available. The value is an unsigned inte‐
1022 ger 0-based index into the backtraceGraph member's nodes
1023 array.
1024 sources
1026 A JSON array of entries corresponding to the target's source
1027 files. Each entry is a JSON object with members:
1028 path A string specifying the path to the source file on disk,
1030 represented with forward slashes. If the file is inside
1031 the top-level source directory then the path is specified
1032 relative to that directory. Otherwise the path is abso‐
1033 lute.
1034 compileGroupIndex
1036 Optional member that is present when the source is com‐
1037 piled. The value is an unsigned integer 0-based index
1038 into the compileGroups array.
1039 sourceGroupIndex
1041 Optional member that is present when the source is part
1042 of a source group either via the source_group() command
1043 or by default. The value is an unsigned integer 0-based
1044 index into the sourceGroups array.
1045 isGenerated
1047 Optional member that is present with boolean value true
1048 if the source is GENERATED.
1049 backtrace
1051 Optional member that is present when a CMake language
1052 backtrace to the target_sources(), add_executable(),
1053 add_library(), add_custom_target(), or other command in‐
1054 vocation that added this source to the target is avail‐
1055 able. The value is an unsigned integer 0-based index
1056 into the backtraceGraph member's nodes array.
1057 sourceGroups
1059 Optional member that is present when sources are grouped to‐
1060 gether by the source_group() command or by default. The value
1061 is a JSON array of entries corresponding to the groups. Each
1062 entry is a JSON object with members:
1063 name A string specifying the name of the source group.
1065 sourceIndexes
1067 A JSON array listing the sources belonging to the group.
1068 Each entry is an unsigned integer 0-based index into the
1069 main sources array for the target.
1070 compileGroups
1072 Optional member that is present when the target has sources that
1073 compile. The value is a JSON array of entries corresponding to
1074 groups of sources that all compile with the same settings. Each
1075 entry is a JSON object with members:
1076 sourceIndexes
1078 A JSON array listing the sources belonging to the group.
1079 Each entry is an unsigned integer 0-based index into the
1080 main sources array for the target.
1081 language
1083 A string specifying the language (e.g. C, CXX, Fortran)
1084 of the toolchain is used to compile the source file.
1085 languageStandard
1087 Optional member that is present when the language stan‐
1088 dard is set explicitly (e.g. via CXX_STANDARD) or implic‐
1089 itly by compile features. Each entry is a JSON object
1090 with two members:
1091 backtraces
1093 Optional member that is present when a CMake lan‐
1094 guage backtrace to the <LANG>_STANDARD setting is
1095 available. If the language standard was set im‐
1096 plicitly by compile features those are used as the
1097 backtrace(s). It's possible for multiple compile
1098 features to require the same language standard so
1099 there could be multiple backtraces. The value is a
1100 JSON array with each entry being an unsigned inte‐
1101 ger 0-based index into the backtraceGraph member's
1102 nodes array.
1103 standard
1105 String representing the language standard.
1106 This field was added in codemodel version 2.2.
1108 compileCommandFragments
1110 Optional member that is present when fragments of the
1111 compiler command line invocation are available. The
1112 value is a JSON array of entries specifying ordered frag‐
1113 ments. Each entry is a JSON object with one member:
1114 fragment
1116 A string specifying a fragment of the compile com‐
1117 mand line invocation. The value is encoded in the
1118 build system's native shell format.
1119 includes
1121 Optional member that is present when there are include
1122 directories. The value is a JSON array with an entry for
1123 each directory. Each entry is a JSON object with mem‐
1124 bers:
1125 path A string specifying the path to the include direc‐
1127 tory, represented with forward slashes.
1128 isSystem
1130 Optional member that is present with boolean value
1131 true if the include directory is marked as a sys‐
1132 tem include directory.
1133 backtrace
1135 Optional member that is present when a CMake lan‐
1136 guage backtrace to the target_include_directo‐
1137 ries() or other command invocation that added this
1138 include directory is available. The value is an
1139 unsigned integer 0-based index into the backtrace‐
1140 Graph member's nodes array.
1141 precompileHeaders
1143 Optional member that is present when target_precom‐
1144 pile_headers() or other command invocations set PRECOM‐
1145 PILE_HEADERS on the target. The value is a JSON array
1146 with an entry for each header. Each entry is a JSON ob‐
1147 ject with members:
1148 header Full path to the precompile header file.
1150 backtrace
1152 Optional member that is present when a CMake lan‐
1153 guage backtrace to the target_precompile_headers()
1154 or other command invocation that added this pre‐
1155 compiled header is available. The value is an un‐
1156 signed integer 0-based index into the backtrace‐
1157 Graph member's nodes array.
1158 This field was added in codemodel version 2.1.
1160 defines
1162 Optional member that is present when there are preproces‐
1163 sor definitions. The value is a JSON array with an entry
1164 for each definition. Each entry is a JSON object with
1165 members:
1166 define A string specifying the preprocessor definition in
1168 the format <name>[=<value>], e.g. DEF or DEF=1.
1169 backtrace
1171 Optional member that is present when a CMake lan‐
1172 guage backtrace to the target_compile_defini‐
1173 tions() or other command invocation that added
1174 this preprocessor definition is available. The
1175 value is an unsigned integer 0-based index into
1176 the backtraceGraph member's nodes array.
1177 sysroot
1179 Optional member that is present when the CMAKE_SYS‐
1180 ROOT_COMPILE or CMAKE_SYSROOT variable is defined. The
1181 value is a JSON object with one member:
1182 path A string specifying the absolute path to the sys‐
1184 root, represented with forward slashes.
1185 backtraceGraph
1187 A "codemodel" version 2 "backtrace graph" whose nodes are refer‐
1188 enced from backtrace members elsewhere in this "target" object.
1189 codemodel version 2 backtrace graph
1191 The backtraceGraph member of a "codemodel" version 2 "directory" ob‐
1192 ject, or "codemodel" version 2 "target" object is a JSON object de‐
1193 scribing a graph of backtraces. Its nodes are referenced from back‐
1194 trace members elsewhere in the containing object. The backtrace graph
1195 object members are:
1196 nodes A JSON array listing nodes in the backtrace graph. Each entry
1198 is a JSON object with members:
1199 file An unsigned integer 0-based index into the backtrace
1201 files array.
1202 line An optional member present when the node represents a
1204 line within the file. The value is an unsigned integer
1205 1-based line number.
1206 command
1208 An optional member present when the node represents a
1209 command invocation within the file. The value is an un‐
1210 signed integer 0-based index into the backtrace commands
1211 array.
1212 parent An optional member present when the node is not the bot‐
1214 tom of the call stack. The value is an unsigned integer
1215 0-based index of another entry in the backtrace nodes ar‐
1216 ray.
1217 commands
1219 A JSON array listing command names referenced by backtrace
1220 nodes. Each entry is a string specifying a command name.
1221 files A JSON array listing CMake language files referenced by back‐
1223 trace nodes. Each entry is a string specifying the path to a
1224 file, represented with forward slashes. If the file is inside
1225 the top-level source directory then the path is specified rela‐
1226 tive to that directory. Otherwise the path is absolute.
1227 Object Kind cache
1229 The cache object kind lists cache entries. These are the CMake Lan‐
1230 guage Variables stored in the persistent cache (CMakeCache.txt) for the
1231 build tree.
1232 There is only one cache object major version, version 2. Version 1
1234 does not exist to avoid confusion with that from cmake-server(7) mode.
1235 cache version 2
1237 cache object version 2 is a JSON object:
1238 {
1240 "kind": "cache",
1241 "version": { "major": 2, "minor": 0 },
1242 "entries": [
1243 {
1244 "name": "BUILD_SHARED_LIBS",
1245 "value": "ON",
1246 "type": "BOOL",
1247 "properties": [
1248 {
1249 "name": "HELPSTRING",
1250 "value": "Build shared libraries"
1251 }
1252 ]
1253 },
1254 {
1255 "name": "CMAKE_GENERATOR",
1256 "value": "Unix Makefiles",
1257 "type": "INTERNAL",
1258 "properties": [
1259 {
1260 "name": "HELPSTRING",
1261 "value": "Name of generator."
1262 }
1263 ]
1264 }
1265 ]
1266 }
1267 The members specific to cache objects are:
1269 entries
1271 A JSON array whose entries are each a JSON object specifying a
1272 cache entry. The members of each entry are:
1273 name A string specifying the name of the entry.
1275 value A string specifying the value of the entry.
1277 type A string specifying the type of the entry used by
1279 cmake-gui(1) to choose a widget for editing.
1280 properties
1282 A JSON array of entries specifying associated cache entry
1283 properties. Each entry is a JSON object containing mem‐
1284 bers:
1285 name A string specifying the name of the cache entry
1287 property.
1288 value A string specifying the value of the cache entry
1290 property.
1291 Object Kind cmakeFiles
1293 The cmakeFiles object kind lists files used by CMake while configuring
1294 and generating the build system. These include the CMakeLists.txt
1295 files as well as included .cmake files.
1296 There is only one cmakeFiles object major version, version 1.
1298 cmakeFiles version 1
1300 cmakeFiles object version 1 is a JSON object:
1301 {
1303 "kind": "cmakeFiles",
1304 "version": { "major": 1, "minor": 0 },
1305 "paths": {
1306 "build": "/path/to/top-level-build-dir",
1307 "source": "/path/to/top-level-source-dir"
1308 },
1309 "inputs": [
1310 {
1311 "path": "CMakeLists.txt"
1312 },
1313 {
1314 "isGenerated": true,
1315 "path": "/path/to/top-level-build-dir/.../CMakeSystem.cmake"
1316 },
1317 {
1318 "isExternal": true,
1319 "path": "/path/to/external/third-party/module.cmake"
1320 },
1321 {
1322 "isCMake": true,
1323 "isExternal": true,
1324 "path": "/path/to/cmake/Modules/CMakeGenericSystem.cmake"
1325 }
1326 ]
1327 }
1328 The members specific to cmakeFiles objects are:
1330 paths A JSON object containing members:
1332 source A string specifying the absolute path to the top-level
1334 source directory, represented with forward slashes.
1335 build A string specifying the absolute path to the top-level
1337 build directory, represented with forward slashes.
1338 inputs A JSON array whose entries are each a JSON object specifying an
1340 input file used by CMake when configuring and generating the
1341 build system. The members of each entry are:
1342 path A string specifying the path to an input file to CMake,
1344 represented with forward slashes. If the file is inside
1345 the top-level source directory then the path is specified
1346 relative to that directory. Otherwise the path is abso‐
1347 lute.
1348 isGenerated
1350 Optional member that is present with boolean value true
1351 if the path specifies a file that is under the top-level
1352 build directory and the build is out-of-source. This
1353 member is not available on in-source builds.
1354 isExternal
1356 Optional member that is present with boolean value true
1357 if the path specifies a file that is not under the
1358 top-level source or build directories.
1359 isCMake
1361 Optional member that is present with boolean value true
1362 if the path specifies a file in the CMake installation.
1363 Object Kind toolchains
1365 The toolchains object kind lists properties of the toolchains used dur‐
1366 ing the build. These include the language, compiler path, ID, and ver‐
1367 sion.
1368 There is only one toolchains object major version, version 1.
1370 toolchains version 1
1372 toolchains object version 1 is a JSON object:
1373 {
1375 "kind": "toolchains",
1376 "version": { "major": 1, "minor": 0 },
1377 "toolchains": [
1378 {
1379 "language": "C",
1380 "compiler": {
1381 "path": "/usr/bin/cc",
1382 "id": "GNU",
1383 "version": "9.3.0",
1384 "implicit": {
1385 "includeDirectories": [
1386 "/usr/lib/gcc/x86_64-linux-gnu/9/include",
1387 "/usr/local/include",
1388 "/usr/include/x86_64-linux-gnu",
1389 "/usr/include"
1390 ],
1391 "linkDirectories": [
1392 "/usr/lib/gcc/x86_64-linux-gnu/9",
1393 "/usr/lib/x86_64-linux-gnu",
1394 "/usr/lib",
1395 "/lib/x86_64-linux-gnu",
1396 "/lib"
1397 ],
1398 "linkFrameworkDirectories": [],
1399 "linkLibraries": [ "gcc", "gcc_s", "c", "gcc", "gcc_s" ]
1400 }
1401 },
1402 "sourceFileExtensions": [ "c", "m" ]
1403 },
1404 {
1405 "language": "CXX",
1406 "compiler": {
1407 "path": "/usr/bin/c++",
1408 "id": "GNU",
1409 "version": "9.3.0",
1410 "implicit": {
1411 "includeDirectories": [
1412 "/usr/include/c++/9",
1413 "/usr/include/x86_64-linux-gnu/c++/9",
1414 "/usr/include/c++/9/backward",
1415 "/usr/lib/gcc/x86_64-linux-gnu/9/include",
1416 "/usr/local/include",
1417 "/usr/include/x86_64-linux-gnu",
1418 "/usr/include"
1419 ],
1420 "linkDirectories": [
1421 "/usr/lib/gcc/x86_64-linux-gnu/9",
1422 "/usr/lib/x86_64-linux-gnu",
1423 "/usr/lib",
1424 "/lib/x86_64-linux-gnu",
1425 "/lib"
1426 ],
1427 "linkFrameworkDirectories": [],
1428 "linkLibraries": [
1429 "stdc++", "m", "gcc_s", "gcc", "c", "gcc_s", "gcc"
1430 ]
1431 }
1432 },
1433 "sourceFileExtensions": [
1434 "C", "M", "c++", "cc", "cpp", "cxx", "mm", "CPP"
1435 ]
1436 }
1437 ]
1438 }
1439 The members specific to toolchains objects are:
1441 toolchains
1443 A JSON array whose entries are each a JSON object specifying a
1444 toolchain associated with a particular language. The members of
1445 each entry are:
1446 language
1448 A JSON string specifying the toolchain language, like C
1449 or CXX. Language names are the same as language names
1450 that can be passed to the project() command. Because
1451 CMake only supports a single toolchain per language, this
1452 field can be used as a key.
1453 compiler
1455 A JSON object containing members:
1456 path Optional member that is present when the
1458 CMAKE_<LANG>_COMPILER variable is defined for the
1459 current language. Its value is a JSON string hold‐
1460 ing the path to the compiler.
1461 id Optional member that is present when the
1463 CMAKE_<LANG>_COMPILER_ID variable is defined for
1464 the current language. Its value is a JSON string
1465 holding the ID (GNU, MSVC, etc.) of the compiler.
1466 version
1468 Optional member that is present when the
1469 CMAKE_<LANG>_COMPILER_VERSION variable is defined
1470 for the current language. Its value is a JSON
1471 string holding the version of the compiler.
1472 target Optional member that is present when the
1474 CMAKE_<LANG>_COMPILER_TARGET variable is defined
1475 for the current language. Its value is a JSON
1476 string holding the cross-compiling target of the
1477 compiler.
1478 implicit
1480 A JSON object containing members:
1481 includeDirectories
1483 Optional member that is present when the
1484 CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES
1485 variable is defined for the current lan‐
1486 guage. Its value is a JSON array of JSON
1487 strings where each string holds a path to
1488 an implicit include directory for the com‐
1489 piler.
1490 linkDirectories
1492 Optional member that is present when the
1493 CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES
1494 variable is defined for the current lan‐
1495 guage. Its value is a JSON array of JSON
1496 strings where each string holds a path to
1497 an implicit link directory for the com‐
1498 piler.
1499 linkFrameworkDirectories
1501 Optional member that is present when the
1502 CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIREC‐
1503 TORIES variable is defined for the current
1504 language. Its value is a JSON array of JSON
1505 strings where each string holds a path to
1506 an implicit link framework directory for
1507 the compiler.
1508 linkLibraries
1510 Optional member that is present when the
1511 CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES vari‐
1512 able is defined for the current language.
1513 Its value is a JSON array of JSON strings
1514 where each string holds a path to an im‐
1515 plicit link library for the compiler.
1516 sourceFileExtensions
1518 Optional member that is present when the
1519 CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS variable is defined
1520 for the current language. Its value is a JSON array of
1521 JSON strings where each each string holds a file exten‐
1522 sion (without the leading dot) for the language.
1523
1525 2000-2021 Kitware, Inc. and Contributors
15263.22.0 Dec 02, 2021 CMAKE-FILE-API(7)