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
265 CMAKE_GENERATOR_PLATFORM, this is a string speci‐
266 fying the generator 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": 4 },
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
612 add_executable(), add_library(), and add_custom_target(),
613 excluding 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
746 install(TARGETS) call with RUNTIME_DEPENDENCIES.
747 The destination member is populated. This type has
748 additional members runtimeDependencySetName and
749 runtimeDependencySetType.
750 fileSet
752 An install(TARGETS) call with FILE_SET. The des‐
753 tination and paths members are populated. The
754 isOptional member may exist. This type has addi‐
755 tional members fileSetName, fileSetType, fileSet‐
756 Directories, and fileSetTarget.
757 This type was added in codemodel version 2.4.
759 isExcludeFromAll
761 Optional member that is present with boolean value true
762 when install() is called with the EXCLUDE_FROM_ALL op‐
763 tion.
764 isForAllComponents
766 Optional member that is present with boolean value true
767 when install(SCRIPT|CODE) is called with the ALL_COMPO‐
768 NENTS option.
769 isOptional
771 Optional member that is present with boolean value true
772 when install() is called with the OPTIONAL option. This
773 is allowed when type is file, directory, or target.
774 targetId
776 Optional member that is present when type is target. The
777 value is a string uniquely identifying the target to be
778 installed. This matches the id member of the target in
779 the main "codemodel" object's targets array.
780 targetIndex
782 Optional member that is present when type is target. The
783 value is an unsigned integer 0-based index into the main
784 "codemodel" object's targets array for the target to be
785 installed.
786 targetIsImportLibrary
788 Optional member that is present when type is target and
789 the installer is for a Windows DLL import library file or
790 for an AIX linker import file. If present, it has bool‐
791 ean value true.
792 targetInstallNamelink
794 Optional member that is present when type is target and
795 the installer corresponds to a target that may use sym‐
796 bolic links to implement the VERSION and SOVERSION target
797 properties. The value is a string indicating how the in‐
798 staller is supposed to handle the symlinks: skip means
799 the installer should skip the symlinks and install only
800 the real file, and only means the installer should in‐
801 stall only the symlinks and not the real file. In all
802 cases the paths member lists what it actually installs.
803 exportName
805 Optional member that is present when type is export. The
806 value is a string specifying the name of the export.
807 exportTargets
809 Optional member that is present when type is export. The
810 value is a JSON array of entries corresponding to the
811 targets included in the export. Each entry is a JSON ob‐
812 ject with members:
813 id A string uniquely identifying the target. This
815 matches the id member of the target in the main
816 "codemodel" object's targets array.
817 index An unsigned integer 0-based index into the main
819 "codemodel" object's targets array for the target.
820 runtimeDependencySetName
822 Optional member that is present when type is runtimeDe‐
823 pendencySet and the installer was created by an
824 install(RUNTIME_DEPENDENCY_SET) call. The value is a
825 string specifying the name of the runtime dependency set
826 that was installed.
827 runtimeDependencySetType
829 Optional member that is present when type is runtimeDe‐
830 pendencySet. The value is a string with one of the fol‐
831 lowing values:
832 library
834 Indicates that this installer installs dependen‐
835 cies that are not macOS frameworks.
836 framework
838 Indicates that this installer installs dependen‐
839 cies that are macOS frameworks.
840 fileSetName
842 Optional member that is present when type is fileSet. The
843 value is a string with the name of the file set.
844 This field was added in codemodel version 2.4.
846 fileSetType
848 Optional member that is present when type is fileSet. The
849 value is a string with the type of the file set.
850 This field was added in codemodel version 2.4.
852 fileSetDirectories
854 Optional member that is present when type is fileSet. The
855 value is a list of strings with the file set's base di‐
856 rectories (determined by genex-evaluation of HEADER_DIRS
857 or HEADER_DIRS_<NAME>).
858 This field was added in codemodel version 2.4.
860 fileSetTarget
862 Optional member that is present when type is fileSet. The
863 value is a JSON object with members:
864 id A string uniquely identifying the target. This
866 matches the id member of the target in the main
867 "codemodel" object's targets array.
868 index An unsigned integer 0-based index into the main
870 "codemodel" object's targets array for the target.
871 This field was added in codemodel version 2.4.
873 scriptFile
875 Optional member that is present when type is script. The
876 value is a string specifying the path to the script file
877 on disk, represented with forward slashes. If the file
878 is inside the top-level source directory then the path is
879 specified relative to that directory. Otherwise the path
880 is absolute.
881 backtrace
883 Optional member that is present when a CMake language
884 backtrace to the install() or other command invocation
885 that added this installer is available. The value is an
886 unsigned integer 0-based index into the backtraceGraph
887 member's nodes array.
888 backtraceGraph
890 A "codemodel" version 2 "backtrace graph" whose nodes are refer‐
891 enced from backtrace members elsewhere in this "directory" ob‐
892 ject.
893 "codemodel" version 2 "target" object
895 A codemodel "target" object is referenced by a "codemodel" version 2
896 object's targets array. Each "target" object is a JSON object with
897 members:
898 name A string specifying the logical name of the target.
900 id A string uniquely identifying the target. The format is unspec‐
902 ified and should not be interpreted by clients.
903 type A string specifying the type of the target. The value is one of
905 EXECUTABLE, STATIC_LIBRARY, SHARED_LIBRARY, MODULE_LIBRARY, OB‐
906 JECT_LIBRARY, INTERFACE_LIBRARY, or UTILITY.
907 backtrace
909 Optional member that is present when a CMake language backtrace
910 to the command in the source code that created the target is
911 available. The value is an unsigned integer 0-based index into
912 the backtraceGraph member's nodes array.
913 folder Optional member that is present when the FOLDER target property
915 is set. The value is a JSON object with one member:
916 name A string specifying the name of the target folder.
918 paths A JSON object containing members:
920 source A string specifying the path to the target's source di‐
922 rectory, represented with forward slashes. If the direc‐
923 tory is inside the top-level source directory then the
924 path is specified relative to that directory (with . for
925 the top-level source directory itself). Otherwise the
926 path is absolute.
927 build A string specifying the path to the target's build direc‐
929 tory, represented with forward slashes. If the directory
930 is inside the top-level build directory then the path is
931 specified relative to that directory (with . for the
932 top-level build directory itself). Otherwise the path is
933 absolute.
934 nameOnDisk
936 Optional member that is present for executable and library tar‐
937 gets that are linked or archived into a single primary artifact.
938 The value is a string specifying the file name of that artifact
939 on disk.
940 artifacts
942 Optional member that is present for executable and library tar‐
943 gets that produce artifacts on disk meant for consumption by de‐
944 pendents. The value is a JSON array of entries corresponding to
945 the artifacts. Each entry is a JSON object containing one mem‐
946 ber:
947 path A string specifying the path to the file on disk, repre‐
949 sented with forward slashes. If the file is inside the
950 top-level build directory then the path is specified rel‐
951 ative to that directory. Otherwise the path is absolute.
952 isGeneratorProvided
954 Optional member that is present with boolean value true if the
955 target is provided by CMake's build system generator rather than
956 by a command in the source code.
957 install
959 Optional member that is present when the target has an install()
960 rule. The value is a JSON object with members:
961 prefix A JSON object specifying the installation prefix. It has
963 one member:
964 path A string specifying the value of
966 CMAKE_INSTALL_PREFIX.
967 destinations
969 A JSON array of entries specifying an install destination
970 path. Each entry is a JSON object with members:
971 path A string specifying the install destination path.
973 The path may be absolute or relative to the in‐
974 stall prefix.
975 backtrace
977 Optional member that is present when a CMake lan‐
978 guage backtrace to the install() command invoca‐
979 tion that specified this destination is available.
980 The value is an unsigned integer 0-based index
981 into the backtraceGraph member's nodes array.
982 link Optional member that is present for executables and shared li‐
984 brary targets that link into a runtime binary. The value is a
985 JSON object with members describing the link step:
986 language
988 A string specifying the language (e.g. C, CXX, Fortran)
989 of the toolchain is used to invoke the linker.
990 commandFragments
992 Optional member that is present when fragments of the
993 link command line invocation are available. The value is
994 a JSON array of entries specifying ordered fragments.
995 Each entry is a JSON object with members:
996 fragment
998 A string specifying a fragment of the link command
999 line invocation. The value is encoded in the
1000 build system's native shell format.
1001 role A string specifying the role of the fragment's
1003 content:
1004 • flags: link flags.
1006 • libraries: link library file paths or flags.
1008 • libraryPath: library search path flags.
1010 • frameworkPath: macOS framework search path
1012 flags.
1013 lto Optional member that is present with boolean value true
1015 when link-time optimization (a.k.a. interprocedural opti‐
1016 mization or link-time code generation) is enabled.
1017 sysroot
1019 Optional member that is present when the
1020 CMAKE_SYSROOT_LINK or CMAKE_SYSROOT variable is defined.
1021 The value is a JSON object with one member:
1022 path A string specifying the absolute path to the sys‐
1024 root, represented with forward slashes.
1025 archive
1027 Optional member that is present for static library targets. The
1028 value is a JSON object with members describing the archive step:
1029 commandFragments
1031 Optional member that is present when fragments of the
1032 archiver command line invocation are available. The
1033 value is a JSON array of entries specifying the frag‐
1034 ments. Each entry is a JSON object with members:
1035 fragment
1037 A string specifying a fragment of the archiver
1038 command line invocation. The value is encoded in
1039 the build system's native shell format.
1040 role A string specifying the role of the fragment's
1042 content:
1043 • flags: archiver flags.
1045 lto Optional member that is present with boolean value true
1047 when link-time optimization (a.k.a. interprocedural opti‐
1048 mization or link-time code generation) is enabled.
1049 dependencies
1051 Optional member that is present when the target depends on other
1052 targets. The value is a JSON array of entries corresponding to
1053 the dependencies. Each entry is a JSON object with members:
1054 id A string uniquely identifying the target on which this
1056 target depends. This matches the main id member of the
1057 other target.
1058 backtrace
1060 Optional member that is present when a CMake language
1061 backtrace to the add_dependencies(),
1062 target_link_libraries(), or other command invocation that
1063 created this dependency is available. The value is an
1064 unsigned integer 0-based index into the backtraceGraph
1065 member's nodes array.
1066 sources
1068 A JSON array of entries corresponding to the target's source
1069 files. Each entry is a JSON object with members:
1070 path A string specifying the path to the source file on disk,
1072 represented with forward slashes. If the file is inside
1073 the top-level source directory then the path is specified
1074 relative to that directory. Otherwise the path is abso‐
1075 lute.
1076 compileGroupIndex
1078 Optional member that is present when the source is com‐
1079 piled. The value is an unsigned integer 0-based index
1080 into the compileGroups array.
1081 sourceGroupIndex
1083 Optional member that is present when the source is part
1084 of a source group either via the source_group() command
1085 or by default. The value is an unsigned integer 0-based
1086 index into the sourceGroups array.
1087 isGenerated
1089 Optional member that is present with boolean value true
1090 if the source is GENERATED.
1091 backtrace
1093 Optional member that is present when a CMake language
1094 backtrace to the target_sources(), add_executable(),
1095 add_library(), add_custom_target(), or other command in‐
1096 vocation that added this source to the target is avail‐
1097 able. The value is an unsigned integer 0-based index
1098 into the backtraceGraph member's nodes array.
1099 sourceGroups
1101 Optional member that is present when sources are grouped to‐
1102 gether by the source_group() command or by default. The value
1103 is a JSON array of entries corresponding to the groups. Each
1104 entry is a JSON object with members:
1105 name A string specifying the name of the source group.
1107 sourceIndexes
1109 A JSON array listing the sources belonging to the group.
1110 Each entry is an unsigned integer 0-based index into the
1111 main sources array for the target.
1112 compileGroups
1114 Optional member that is present when the target has sources that
1115 compile. The value is a JSON array of entries corresponding to
1116 groups of sources that all compile with the same settings. Each
1117 entry is a JSON object with members:
1118 sourceIndexes
1120 A JSON array listing the sources belonging to the group.
1121 Each entry is an unsigned integer 0-based index into the
1122 main sources array for the target.
1123 language
1125 A string specifying the language (e.g. C, CXX, Fortran)
1126 of the toolchain is used to compile the source file.
1127 languageStandard
1129 Optional member that is present when the language stan‐
1130 dard is set explicitly (e.g. via CXX_STANDARD) or implic‐
1131 itly by compile features. Each entry is a JSON object
1132 with two members:
1133 backtraces
1135 Optional member that is present when a CMake lan‐
1136 guage backtrace to the <LANG>_STANDARD setting is
1137 available. If the language standard was set im‐
1138 plicitly by compile features those are used as the
1139 backtrace(s). It's possible for multiple compile
1140 features to require the same language standard so
1141 there could be multiple backtraces. The value is a
1142 JSON array with each entry being an unsigned inte‐
1143 ger 0-based index into the backtraceGraph member's
1144 nodes array.
1145 standard
1147 String representing the language standard.
1148 This field was added in codemodel version 2.2.
1150 compileCommandFragments
1152 Optional member that is present when fragments of the
1153 compiler command line invocation are available. The
1154 value is a JSON array of entries specifying ordered frag‐
1155 ments. Each entry is a JSON object with one member:
1156 fragment
1158 A string specifying a fragment of the compile com‐
1159 mand line invocation. The value is encoded in the
1160 build system's native shell format.
1161 includes
1163 Optional member that is present when there are include
1164 directories. The value is a JSON array with an entry for
1165 each directory. Each entry is a JSON object with mem‐
1166 bers:
1167 path A string specifying the path to the include direc‐
1169 tory, represented with forward slashes.
1170 isSystem
1172 Optional member that is present with boolean value
1173 true if the include directory is marked as a sys‐
1174 tem include directory.
1175 backtrace
1177 Optional member that is present when a CMake lan‐
1178 guage backtrace to the
1179 target_include_directories() or other command in‐
1180 vocation that added this include directory is
1181 available. The value is an unsigned integer
1182 0-based index into the backtraceGraph member's
1183 nodes array.
1184 precompileHeaders
1186 Optional member that is present when
1187 target_precompile_headers() or other command invocations
1188 set PRECOMPILE_HEADERS on the target. The value is a
1189 JSON array with an entry for each header. Each entry is
1190 a JSON object with members:
1191 header Full path to the precompile header file.
1193 backtrace
1195 Optional member that is present when a CMake lan‐
1196 guage backtrace to the target_precompile_headers()
1197 or other command invocation that added this pre‐
1198 compiled header is available. The value is an un‐
1199 signed integer 0-based index into the backtrace‐
1200 Graph member's nodes array.
1201 This field was added in codemodel version 2.1.
1203 defines
1205 Optional member that is present when there are preproces‐
1206 sor definitions. The value is a JSON array with an entry
1207 for each definition. Each entry is a JSON object with
1208 members:
1209 define A string specifying the preprocessor definition in
1211 the format <name>[=<value>], e.g. DEF or DEF=1.
1212 backtrace
1214 Optional member that is present when a CMake lan‐
1215 guage backtrace to the
1216 target_compile_definitions() or other command in‐
1217 vocation that added this preprocessor definition
1218 is available. The value is an unsigned integer
1219 0-based index into the backtraceGraph member's
1220 nodes array.
1221 sysroot
1223 Optional member that is present when the
1224 CMAKE_SYSROOT_COMPILE or CMAKE_SYSROOT variable is de‐
1225 fined. The value is a JSON object with one member:
1226 path A string specifying the absolute path to the sys‐
1228 root, represented with forward slashes.
1229 backtraceGraph
1231 A "codemodel" version 2 "backtrace graph" whose nodes are refer‐
1232 enced from backtrace members elsewhere in this "target" object.
1233 "codemodel" version 2 "backtrace graph"
1235 The backtraceGraph member of a "codemodel" version 2 "directory" ob‐
1236 ject, or "codemodel" version 2 "target" object is a JSON object de‐
1237 scribing a graph of backtraces. Its nodes are referenced from back‐
1238 trace members elsewhere in the containing object. The backtrace graph
1239 object members are:
1240 nodes A JSON array listing nodes in the backtrace graph. Each entry
1242 is a JSON object with members:
1243 file An unsigned integer 0-based index into the backtrace
1245 files array.
1246 line An optional member present when the node represents a
1248 line within the file. The value is an unsigned integer
1249 1-based line number.
1250 command
1252 An optional member present when the node represents a
1253 command invocation within the file. The value is an un‐
1254 signed integer 0-based index into the backtrace commands
1255 array.
1256 parent An optional member present when the node is not the bot‐
1258 tom of the call stack. The value is an unsigned integer
1259 0-based index of another entry in the backtrace nodes ar‐
1260 ray.
1261 commands
1263 A JSON array listing command names referenced by backtrace
1264 nodes. Each entry is a string specifying a command name.
1265 files A JSON array listing CMake language files referenced by back‐
1267 trace nodes. Each entry is a string specifying the path to a
1268 file, represented with forward slashes. If the file is inside
1269 the top-level source directory then the path is specified rela‐
1270 tive to that directory. Otherwise the path is absolute.
1271 Object Kind "cache"
1273 The cache object kind lists cache entries. These are the Variables
1274 stored in the persistent cache (CMakeCache.txt) for the build tree.
1275 There is only one cache object major version, version 2. Version 1
1277 does not exist to avoid confusion with that from cmake-server(7) mode.
1278 "cache" version 2
1280 cache object version 2 is a JSON object:
1281 {
1283 "kind": "cache",
1284 "version": { "major": 2, "minor": 0 },
1285 "entries": [
1286 {
1287 "name": "BUILD_SHARED_LIBS",
1288 "value": "ON",
1289 "type": "BOOL",
1290 "properties": [
1291 {
1292 "name": "HELPSTRING",
1293 "value": "Build shared libraries"
1294 }
1295 ]
1296 },
1297 {
1298 "name": "CMAKE_GENERATOR",
1299 "value": "Unix Makefiles",
1300 "type": "INTERNAL",
1301 "properties": [
1302 {
1303 "name": "HELPSTRING",
1304 "value": "Name of generator."
1305 }
1306 ]
1307 }
1308 ]
1309 }
1310 The members specific to cache objects are:
1312 entries
1314 A JSON array whose entries are each a JSON object specifying a
1315 cache entry. The members of each entry are:
1316 name A string specifying the name of the entry.
1318 value A string specifying the value of the entry.
1320 type A string specifying the type of the entry used by
1322 cmake-gui(1) to choose a widget for editing.
1323 properties
1325 A JSON array of entries specifying associated cache entry
1326 properties. Each entry is a JSON object containing mem‐
1327 bers:
1328 name A string specifying the name of the cache entry
1330 property.
1331 value A string specifying the value of the cache entry
1333 property.
1334 Object Kind "cmakeFiles"
1336 The cmakeFiles object kind lists files used by CMake while configuring
1337 and generating the build system. These include the CMakeLists.txt
1338 files as well as included .cmake files.
1339 There is only one cmakeFiles object major version, version 1.
1341 "cmakeFiles" version 1
1343 cmakeFiles object version 1 is a JSON object:
1344 {
1346 "kind": "cmakeFiles",
1347 "version": { "major": 1, "minor": 0 },
1348 "paths": {
1349 "build": "/path/to/top-level-build-dir",
1350 "source": "/path/to/top-level-source-dir"
1351 },
1352 "inputs": [
1353 {
1354 "path": "CMakeLists.txt"
1355 },
1356 {
1357 "isGenerated": true,
1358 "path": "/path/to/top-level-build-dir/.../CMakeSystem.cmake"
1359 },
1360 {
1361 "isExternal": true,
1362 "path": "/path/to/external/third-party/module.cmake"
1363 },
1364 {
1365 "isCMake": true,
1366 "isExternal": true,
1367 "path": "/path/to/cmake/Modules/CMakeGenericSystem.cmake"
1368 }
1369 ]
1370 }
1371 The members specific to cmakeFiles objects are:
1373 paths A JSON object containing members:
1375 source A string specifying the absolute path to the top-level
1377 source directory, represented with forward slashes.
1378 build A string specifying the absolute path to the top-level
1380 build directory, represented with forward slashes.
1381 inputs A JSON array whose entries are each a JSON object specifying an
1383 input file used by CMake when configuring and generating the
1384 build system. The members of each entry are:
1385 path A string specifying the path to an input file to CMake,
1387 represented with forward slashes. If the file is inside
1388 the top-level source directory then the path is specified
1389 relative to that directory. Otherwise the path is abso‐
1390 lute.
1391 isGenerated
1393 Optional member that is present with boolean value true
1394 if the path specifies a file that is under the top-level
1395 build directory and the build is out-of-source. This
1396 member is not available on in-source builds.
1397 isExternal
1399 Optional member that is present with boolean value true
1400 if the path specifies a file that is not under the
1401 top-level source or build directories.
1402 isCMake
1404 Optional member that is present with boolean value true
1405 if the path specifies a file in the CMake installation.
1406 Object Kind "toolchains"
1408 The toolchains object kind lists properties of the toolchains used dur‐
1409 ing the build. These include the language, compiler path, ID, and ver‐
1410 sion.
1411 There is only one toolchains object major version, version 1.
1413 "toolchains" version 1
1415 toolchains object version 1 is a JSON object:
1416 {
1418 "kind": "toolchains",
1419 "version": { "major": 1, "minor": 0 },
1420 "toolchains": [
1421 {
1422 "language": "C",
1423 "compiler": {
1424 "path": "/usr/bin/cc",
1425 "id": "GNU",
1426 "version": "9.3.0",
1427 "implicit": {
1428 "includeDirectories": [
1429 "/usr/lib/gcc/x86_64-linux-gnu/9/include",
1430 "/usr/local/include",
1431 "/usr/include/x86_64-linux-gnu",
1432 "/usr/include"
1433 ],
1434 "linkDirectories": [
1435 "/usr/lib/gcc/x86_64-linux-gnu/9",
1436 "/usr/lib/x86_64-linux-gnu",
1437 "/usr/lib",
1438 "/lib/x86_64-linux-gnu",
1439 "/lib"
1440 ],
1441 "linkFrameworkDirectories": [],
1442 "linkLibraries": [ "gcc", "gcc_s", "c", "gcc", "gcc_s" ]
1443 }
1444 },
1445 "sourceFileExtensions": [ "c", "m" ]
1446 },
1447 {
1448 "language": "CXX",
1449 "compiler": {
1450 "path": "/usr/bin/c++",
1451 "id": "GNU",
1452 "version": "9.3.0",
1453 "implicit": {
1454 "includeDirectories": [
1455 "/usr/include/c++/9",
1456 "/usr/include/x86_64-linux-gnu/c++/9",
1457 "/usr/include/c++/9/backward",
1458 "/usr/lib/gcc/x86_64-linux-gnu/9/include",
1459 "/usr/local/include",
1460 "/usr/include/x86_64-linux-gnu",
1461 "/usr/include"
1462 ],
1463 "linkDirectories": [
1464 "/usr/lib/gcc/x86_64-linux-gnu/9",
1465 "/usr/lib/x86_64-linux-gnu",
1466 "/usr/lib",
1467 "/lib/x86_64-linux-gnu",
1468 "/lib"
1469 ],
1470 "linkFrameworkDirectories": [],
1471 "linkLibraries": [
1472 "stdc++", "m", "gcc_s", "gcc", "c", "gcc_s", "gcc"
1473 ]
1474 }
1475 },
1476 "sourceFileExtensions": [
1477 "C", "M", "c++", "cc", "cpp", "cxx", "mm", "CPP"
1478 ]
1479 }
1480 ]
1481 }
1482 The members specific to toolchains objects are:
1484 toolchains
1486 A JSON array whose entries are each a JSON object specifying a
1487 toolchain associated with a particular language. The members of
1488 each entry are:
1489 language
1491 A JSON string specifying the toolchain language, like C
1492 or CXX. Language names are the same as language names
1493 that can be passed to the project() command. Because
1494 CMake only supports a single toolchain per language, this
1495 field can be used as a key.
1496 compiler
1498 A JSON object containing members:
1499 path Optional member that is present when the
1501 CMAKE_<LANG>_COMPILER variable is defined for the
1502 current language. Its value is a JSON string hold‐
1503 ing the path to the compiler.
1504 id Optional member that is present when the
1506 CMAKE_<LANG>_COMPILER_ID variable is defined for
1507 the current language. Its value is a JSON string
1508 holding the ID (GNU, MSVC, etc.) of the compiler.
1509 version
1511 Optional member that is present when the
1512 CMAKE_<LANG>_COMPILER_VERSION variable is defined
1513 for the current language. Its value is a JSON
1514 string holding the version of the compiler.
1515 target Optional member that is present when the
1517 CMAKE_<LANG>_COMPILER_TARGET variable is defined
1518 for the current language. Its value is a JSON
1519 string holding the cross-compiling target of the
1520 compiler.
1521 implicit
1523 A JSON object containing members:
1524 includeDirectories
1526 Optional member that is present when the
1527 CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES
1528 variable is defined for the current lan‐
1529 guage. Its value is a JSON array of JSON
1530 strings where each string holds a path to
1531 an implicit include directory for the com‐
1532 piler.
1533 linkDirectories
1535 Optional member that is present when the
1536 CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES
1537 variable is defined for the current lan‐
1538 guage. Its value is a JSON array of JSON
1539 strings where each string holds a path to
1540 an implicit link directory for the com‐
1541 piler.
1542 linkFrameworkDirectories
1544 Optional member that is present when the
1545 CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES
1546 variable is defined for the current lan‐
1547 guage. Its value is a JSON array of JSON
1548 strings where each string holds a path to
1549 an implicit link framework directory for
1550 the compiler.
1551 linkLibraries
1553 Optional member that is present when the
1554 CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES vari‐
1555 able is defined for the current language.
1556 Its value is a JSON array of JSON strings
1557 where each string holds a path to an im‐
1558 plicit link library for the compiler.
1559 sourceFileExtensions
1561 Optional member that is present when the
1562 CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS variable is defined
1563 for the current language. Its value is a JSON array of
1564 JSON strings where each each string holds a file exten‐
1565 sion (without the leading dot) for the language.
1566
1568 2000-2023 Kitware, Inc. and Contributors
15693.25.2 Jan 19, 2023 CMAKE-FILE-API(7)