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
144 major 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
164 selected by CMake. Whenever a new index file is generated it is given
165 a 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
292 directory 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
335 requests array, in the same order. Each
336 response 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
344 object 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
372 reply. However, after generating a new reply CMake will attempt to
373 remove 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
376 reply. The client may simply start again by reading the new reply
377 index 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
383 minor 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": 0 },
409 "paths": {
410 "source": "/path/to/top-level-source-dir",
411 "build": "/path/to/top-level-build-dir"
412 },
413 "configurations": [
414 {
415 "name": "Debug",
416 "directories": [
417 {
418 "source": ".",
419 "build": ".",
420 "childIndexes": [ 1 ],
421 "projectIndex": 0,
422 "targetIndexes": [ 0 ],
423 "hasInstallRule": true,
424 "minimumCMakeVersion": {
425 "string": "3.14"
426 }
427 },
428 {
429 "source": "sub",
430 "build": "sub",
431 "parentIndex": 0,
432 "projectIndex": 0,
433 "targetIndexes": [ 1 ],
434 "minimumCMakeVersion": {
435 "string": "3.14"
436 }
437 }
438 ],
439 "projects": [
440 {
441 "name": "MyProject",
442 "directoryIndexes": [ 0, 1 ],
443 "targetIndexes": [ 0, 1 ]
444 }
445 ],
446 "targets": [
447 {
448 "name": "MyExecutable",
449 "directoryIndex": 0,
450 "projectIndex": 0,
451 "jsonFile": "<file>"
452 },
453 {
454 "name": "MyLibrary",
455 "directoryIndex": 1,
456 "projectIndex": 0,
457 "jsonFile": "<file>"
458 }
459 ]
460 }
461 ]
462 }
463 The members specific to codemodel objects are:
465 paths A JSON object containing members:
467 source A string specifying the absolute path to the top-level
469 source directory, represented with forward slashes.
470 build A string specifying the absolute path to the top-level
472 build directory, represented with forward slashes.
473 configurations
475 A JSON array of entries corresponding to available build config‐
476 urations. On single-configuration generators there is one entry
477 for the value of the CMAKE_BUILD_TYPE variable. For multi-con‐
478 figuration generators there is an entry for each configuration
479 listed in the CMAKE_CONFIGURATION_TYPES variable. Each entry is
480 a JSON object containing members:
481 name A string specifying the name of the configuration, e.g.
483 Debug.
484 directories
486 A JSON array of entries each corresponding to a build
487 system directory whose source directory contains a CMake‐
488 Lists.txt file. The first entry corresponds to the
489 top-level directory. Each entry is a JSON object con‐
490 taining members:
491 source A string specifying the path to the source direc‐
493 tory, represented with forward slashes. If the
494 directory is inside the top-level source directory
495 then the path is specified relative to that direc‐
496 tory (with . for the top-level source directory
497 itself). Otherwise the path is absolute.
498 build A string specifying the path to the build direc‐
500 tory, represented with forward slashes. If the
501 directory is inside the top-level build directory
502 then the path is specified relative to that direc‐
503 tory (with . for the top-level build directory
504 itself). Otherwise the path is absolute.
505 parentIndex
507 Optional member that is present when the directory
508 is not top-level. The value is an unsigned inte‐
509 ger 0-based index of another entry in the main
510 directories array that corresponds to the parent
511 directory that added this directory as a subdirec‐
512 tory.
513 childIndexes
515 Optional member that is present when the directory
516 has subdirectories. The value is a JSON array of
517 entries corresponding to child directories created
518 by the add_subdirectory() or subdirs() command.
519 Each entry is an unsigned integer 0-based index of
520 another entry in the main directories array.
521 projectIndex
523 An unsigned integer 0-based index into the main
524 projects array indicating the build system project
525 to which the this directory belongs.
526 targetIndexes
528 Optional member that is present when the directory
529 itself has targets, excluding those belonging to
530 subdirectories. The value is a JSON array of
531 entries corresponding to the targets. Each entry
532 is an unsigned integer 0-based index into the main
533 targets array.
534 minimumCMakeVersion
536 Optional member present when a minimum required
537 version of CMake is known for the directory. This
538 is the <min> version given to the most local call
539 to the cmake_minimum_required(VERSION) command in
540 the directory itself or one of its ancestors. The
541 value is a JSON object with one member:
542 string A string specifying the minimum required
544 version in the format:
545 <major>.<minor>[.<patch>[.<tweak>]][<suffix>]
547 Each component is an unsigned integer and
549 the suffix may be an arbitrary string.
550 hasInstallRule
552 Optional member that is present with boolean value
553 true when the directory or one of its subdirecto‐
554 ries contains any install() rules, i.e. whether a
555 make install or equivalent rule is available.
556 projects
558 A JSON array of entries corresponding to the top-level
559 project and sub-projects defined in the build system.
560 Each (sub-)project corresponds to a source directory
561 whose CMakeLists.txt file calls the project() command
562 with a project name different from its parent directory.
563 The first entry corresponds to the top-level project.
564 Each entry is a JSON object containing members:
566 name A string specifying the name given to the
568 project() command.
569 parentIndex
571 Optional member that is present when the project
572 is not top-level. The value is an unsigned inte‐
573 ger 0-based index of another entry in the main
574 projects array that corresponds to the parent
575 project that added this project as a sub-project.
576 childIndexes
578 Optional member that is present when the project
579 has sub-projects. The value is a JSON array of
580 entries corresponding to the sub-projects. Each
581 entry is an unsigned integer 0-based index of
582 another entry in the main projects array.
583 directoryIndexes
585 A JSON array of entries corresponding to build
586 system directories that are part of the project.
587 The first entry corresponds to the top-level
588 directory of the project. Each entry is an
589 unsigned integer 0-based index into the main
590 directories array.
591 targetIndexes
593 Optional member that is present when the project
594 itself has targets, excluding those belonging to
595 sub-projects. The value is a JSON array of
596 entries corresponding to the targets. Each entry
597 is an unsigned integer 0-based index into the main
598 targets array.
599 targets
601 A JSON array of entries corresponding to the build system
602 targets. Such targets are created by calls to add_exe‐
603 cutable(), add_library(), and add_custom_target(),
604 excluding imported targets and interface libraries (which
605 do not generate any build rules). Each entry is a JSON
606 object containing members:
607 name A string specifying the target name.
609 id A string uniquely identifying the target. This
611 matches the id field in the file referenced by
612 jsonFile.
613 directoryIndex
615 An unsigned integer 0-based index into the main
616 directories array indicating the build system
617 directory in which the target is defined.
618 projectIndex
620 An unsigned integer 0-based index into the main
621 projects array indicating the build system project
622 in which the target is defined.
623 jsonFile
625 A JSON string specifying a path relative to the
626 codemodel file to another JSON file containing a
627 “codemodel” version 2 “target” object.
628 “codemodel” version 2 “target” object
630 A codemodel “target” object is referenced by a “codemodel” version 2
631 object’s targets array. Each “target” object is a JSON object with
632 members:
633 name A string specifying the logical name of the target.
635 id A string uniquely identifying the target. The format is unspec‐
637 ified and should not be interpreted by clients.
638 type A string specifying the type of the target. The value is one of
640 EXECUTABLE, STATIC_LIBRARY, SHARED_LIBRARY, MODULE_LIBRARY,
641 OBJECT_LIBRARY, or UTILITY.
642 backtrace
644 Optional member that is present when a CMake language backtrace
645 to the command in the source code that created the target is
646 available. The value is an unsigned integer 0-based index into
647 the backtraceGraph member’s nodes array.
648 folder Optional member that is present when the FOLDER target property
650 is set. The value is a JSON object with one member:
651 name A string specifying the name of the target folder.
653 paths A JSON object containing members:
655 source A string specifying the path to the target’s source
657 directory, represented with forward slashes. If the
658 directory is inside the top-level source directory then
659 the path is specified relative to that directory (with .
660 for the top-level source directory itself). Otherwise
661 the path is absolute.
662 build A string specifying the path to the target’s build direc‐
664 tory, represented with forward slashes. If the directory
665 is inside the top-level build directory then the path is
666 specified relative to that directory (with . for the
667 top-level build directory itself). Otherwise the path is
668 absolute.
669 nameOnDisk
671 Optional member that is present for executable and library tar‐
672 gets that are linked or archived into a single primary artifact.
673 The value is a string specifying the file name of that artifact
674 on disk.
675 artifacts
677 Optional member that is present for executable and library tar‐
678 gets that produce artifacts on disk meant for consumption by
679 dependents. The value is a JSON array of entries corresponding
680 to the artifacts. Each entry is a JSON object containing one
681 member:
682 path A string specifying the path to the file on disk, repre‐
684 sented with forward slashes. If the file is inside the
685 top-level build directory then the path is specified rel‐
686 ative to that directory. Otherwise the path is absolute.
687 isGeneratorProvided
689 Optional member that is present with boolean value true if the
690 target is provided by CMake’s build system generator rather than
691 by a command in the source code.
692 install
694 Optional member that is present when the target has an install()
695 rule. The value is a JSON object with members:
696 prefix A JSON object specifying the installation prefix. It has
698 one member:
699 path A string specifying the value of
701 CMAKE_INSTALL_PREFIX.
702 destinations
704 A JSON array of entries specifying an install destination
705 path. Each entry is a JSON object with members:
706 path A string specifying the install destination path.
708 The path may be absolute or relative to the
709 install prefix.
710 backtrace
712 Optional member that is present when a CMake lan‐
713 guage backtrace to the install() command invoca‐
714 tion that specified this destination is available.
715 The value is an unsigned integer 0-based index
716 into the backtraceGraph member’s nodes array.
717 link Optional member that is present for executables and shared
719 library targets that link into a runtime binary. The value is a
720 JSON object with members describing the link step:
721 language
723 A string specifying the language (e.g. C, CXX, Fortran)
724 of the toolchain is used to invoke the linker.
725 commandFragments
727 Optional member that is present when fragments of the
728 link command line invocation are available. The value is
729 a JSON array of entries specifying ordered fragments.
730 Each entry is a JSON object with members:
731 fragment
733 A string specifying a fragment of the link command
734 line invocation. The value is encoded in the
735 build system’s native shell format.
736 role A string specifying the role of the fragment’s
738 content:
739 · flags: link flags.
741 · libraries: link library file paths or flags.
743 · libraryPath: library search path flags.
745 · frameworkPath: macOS framework search path
747 flags.
748 lto Optional member that is present with boolean value true
750 when link-time optimization (a.k.a. interprocedural opti‐
751 mization or link-time code generation) is enabled.
752 sysroot
754 Optional member that is present when the CMAKE_SYS‐
755 ROOT_LINK or CMAKE_SYSROOT variable is defined. The
756 value is a JSON object with one member:
757 path A string specifying the absolute path to the sys‐
759 root, represented with forward slashes.
760 archive
762 Optional member that is present for static library targets. The
763 value is a JSON object with members describing the archive step:
764 commandFragments
766 Optional member that is present when fragments of the
767 archiver command line invocation are available. The
768 value is a JSON array of entries specifying the frag‐
769 ments. Each entry is a JSON object with members:
770 fragment
772 A string specifying a fragment of the archiver
773 command line invocation. The value is encoded in
774 the build system’s native shell format.
775 role A string specifying the role of the fragment’s
777 content:
778 · flags: archiver flags.
780 lto Optional member that is present with boolean value true
782 when link-time optimization (a.k.a. interprocedural opti‐
783 mization or link-time code generation) is enabled.
784 dependencies
786 Optional member that is present when the target depends on other
787 targets. The value is a JSON array of entries corresponding to
788 the dependencies. Each entry is a JSON object with members:
789 id A string uniquely identifying the target on which this
791 target depends. This matches the main id member of the
792 other target.
793 backtrace
795 Optional member that is present when a CMake language
796 backtrace to the add_dependencies(), tar‐
797 get_link_libraries(), or other command invocation that
798 created this dependency is available. The value is an
799 unsigned integer 0-based index into the backtraceGraph
800 member’s nodes array.
801 sources
803 A JSON array of entries corresponding to the target’s source
804 files. Each entry is a JSON object with members:
805 path A string specifying the path to the source file on disk,
807 represented with forward slashes. If the file is inside
808 the top-level source directory then the path is specified
809 relative to that directory. Otherwise the path is abso‐
810 lute.
811 compileGroupIndex
813 Optional member that is present when the source is com‐
814 piled. The value is an unsigned integer 0-based index
815 into the compileGroups array.
816 sourceGroupIndex
818 Optional member that is present when the source is part
819 of a source group either via the source_group() command
820 or by default. The value is an unsigned integer 0-based
821 index into the sourceGroups array.
822 isGenerated
824 Optional member that is present with boolean value true
825 if the source is GENERATED.
826 backtrace
828 Optional member that is present when a CMake language
829 backtrace to the target_sources(), add_executable(),
830 add_library(), add_custom_target(), or other command
831 invocation that added this source to the target is avail‐
832 able. The value is an unsigned integer 0-based index
833 into the backtraceGraph member’s nodes array.
834 sourceGroups
836 Optional member that is present when sources are grouped
837 together by the source_group() command or by default. The value
838 is a JSON array of entries corresponding to the groups. Each
839 entry is a JSON object with members:
840 name A string specifying the name of the source group.
842 sourceIndexes
844 A JSON array listing the sources belonging to the group.
845 Each entry is an unsigned integer 0-based index into the
846 main sources array for the target.
847 compileGroups
849 Optional member that is present when the target has sources that
850 compile. The value is a JSON array of entries corresponding to
851 groups of sources that all compile with the same settings. Each
852 entry is a JSON object with members:
853 sourceIndexes
855 A JSON array listing the sources belonging to the group.
856 Each entry is an unsigned integer 0-based index into the
857 main sources array for the target.
858 language
860 A string specifying the language (e.g. C, CXX, Fortran)
861 of the toolchain is used to compile the source file.
862 compileCommandFragments
864 Optional member that is present when fragments of the
865 compiler command line invocation are available. The
866 value is a JSON array of entries specifying ordered frag‐
867 ments. Each entry is a JSON object with one member:
868 fragment
870 A string specifying a fragment of the compile com‐
871 mand line invocation. The value is encoded in the
872 build system’s native shell format.
873 includes
875 Optional member that is present when there are include
876 directories. The value is a JSON array with an entry for
877 each directory. Each entry is a JSON object with mem‐
878 bers:
879 path A string specifying the path to the include direc‐
881 tory, represented with forward slashes.
882 isSystem
884 Optional member that is present with boolean value
885 true if the include directory is marked as a sys‐
886 tem include directory.
887 backtrace
889 Optional member that is present when a CMake lan‐
890 guage backtrace to the target_include_directo‐
891 ries() or other command invocation that added this
892 include directory is available. The value is an
893 unsigned integer 0-based index into the backtrace‐
894 Graph member’s nodes array.
895 defines
897 Optional member that is present when there are preproces‐
898 sor definitions. The value is a JSON array with an entry
899 for each definition. Each entry is a JSON object with
900 members:
901 define A string specifying the preprocessor definition in
903 the format <name>[=<value>], e.g. DEF or DEF=1.
904 backtrace
906 Optional member that is present when a CMake lan‐
907 guage backtrace to the target_compile_defini‐
908 tions() or other command invocation that added
909 this preprocessor definition is available. The
910 value is an unsigned integer 0-based index into
911 the backtraceGraph member’s nodes array.
912 sysroot
914 Optional member that is present when the CMAKE_SYS‐
915 ROOT_COMPILE or CMAKE_SYSROOT variable is defined. The
916 value is a JSON object with one member:
917 path A string specifying the absolute path to the sys‐
919 root, represented with forward slashes.
920 backtraceGraph
922 A JSON object describing the graph of backtraces whose nodes are
923 referenced from backtrace members elsewhere. The members are:
924 nodes A JSON array listing nodes in the backtrace graph. Each
926 entry is a JSON object with members:
927 file An unsigned integer 0-based index into the back‐
929 trace files array.
930 line An optional member present when the node repre‐
932 sents a line within the file. The value is an
933 unsigned integer 1-based line number.
934 command
936 An optional member present when the node repre‐
937 sents a command invocation within the file. The
938 value is an unsigned integer 0-based index into
939 the backtrace commands array.
940 parent An optional member present when the node is not
942 the bottom of the call stack. The value is an
943 unsigned integer 0-based index of another entry in
944 the backtrace nodes array.
945 commands
947 A JSON array listing command names referenced by back‐
948 trace nodes. Each entry is a string specifying a command
949 name.
950 files A JSON array listing CMake language files referenced by
952 backtrace nodes. Each entry is a string specifying the
953 path to a file, represented with forward slashes. If the
954 file is inside the top-level source directory then the
955 path is specified relative to that directory. Otherwise
956 the path is absolute.
957 Object Kind “cache”
959 The cache object kind lists cache entries. These are the CMake Lan‐
960 guage Variables stored in the persistent cache (CMakeCache.txt) for the
961 build tree.
962 There is only one cache object major version, version 2. Version 1
964 does not exist to avoid confusion with that from cmake-server(7) mode.
965 “cache” version 2
967 cache object version 2 is a JSON object:
968 {
970 "kind": "cache",
971 "version": { "major": 2, "minor": 0 },
972 "entries": [
973 {
974 "name": "BUILD_SHARED_LIBS",
975 "value": "ON",
976 "type": "BOOL",
977 "properties": [
978 {
979 "name": "HELPSTRING",
980 "value": "Build shared libraries"
981 }
982 ]
983 },
984 {
985 "name": "CMAKE_GENERATOR",
986 "value": "Unix Makefiles",
987 "type": "INTERNAL",
988 "properties": [
989 {
990 "name": "HELPSTRING",
991 "value": "Name of generator."
992 }
993 ]
994 }
995 ]
996 }
997 The members specific to cache objects are:
999 entries
1001 A JSON array whose entries are each a JSON object specifying a
1002 cache entry. The members of each entry are:
1003 name A string specifying the name of the entry.
1005 value A string specifying the value of the entry.
1007 type A string specifying the type of the entry used by
1009 cmake-gui(1) to choose a widget for editing.
1010 properties
1012 A JSON array of entries specifying associated cache entry
1013 properties. Each entry is a JSON object containing mem‐
1014 bers:
1015 name A string specifying the name of the cache entry
1017 property.
1018 value A string specifying the value of the cache entry
1020 property.
1021 Object Kind “cmakeFiles”
1023 The cmakeFiles object kind lists files used by CMake while configuring
1024 and generating the build system. These include the CMakeLists.txt
1025 files as well as included .cmake files.
1026 There is only one cmakeFiles object major version, version 1.
1028 “cmakeFiles” version 1
1030 cmakeFiles object version 1 is a JSON object:
1031 {
1033 "kind": "cmakeFiles",
1034 "version": { "major": 1, "minor": 0 },
1035 "paths": {
1036 "build": "/path/to/top-level-build-dir",
1037 "source": "/path/to/top-level-source-dir"
1038 },
1039 "inputs": [
1040 {
1041 "path": "CMakeLists.txt"
1042 },
1043 {
1044 "isGenerated": true,
1045 "path": "/path/to/top-level-build-dir/.../CMakeSystem.cmake"
1046 },
1047 {
1048 "isExternal": true,
1049 "path": "/path/to/external/third-party/module.cmake"
1050 },
1051 {
1052 "isCMake": true,
1053 "isExternal": true,
1054 "path": "/path/to/cmake/Modules/CMakeGenericSystem.cmake"
1055 }
1056 ]
1057 }
1058 The members specific to cmakeFiles objects are:
1060 paths A JSON object containing members:
1062 source A string specifying the absolute path to the top-level
1064 source directory, represented with forward slashes.
1065 build A string specifying the absolute path to the top-level
1067 build directory, represented with forward slashes.
1068 inputs A JSON array whose entries are each a JSON object specifying an
1070 input file used by CMake when configuring and generating the
1071 build system. The members of each entry are:
1072 path A string specifying the path to an input file to CMake,
1074 represented with forward slashes. If the file is inside
1075 the top-level source directory then the path is specified
1076 relative to that directory. Otherwise the path is abso‐
1077 lute.
1078 isGenerated
1080 Optional member that is present with boolean value true
1081 if the path specifies a file that is under the top-level
1082 build directory and the build is out-of-source. This
1083 member is not available on in-source builds.
1084 isExternal
1086 Optional member that is present with boolean value true
1087 if the path specifies a file that is not under the
1088 top-level source or build directories.
1089 isCMake
1091 Optional member that is present with boolean value true
1092 if the path specifies a file in the CMake installation.
1093
1095 2000-2020 Kitware, Inc. and Contributors
10963.17.2 Apr 28, 2020 CMAKE-FILE-API(7)