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 "name": "Unix Makefiles"
185 }
186 },
187 "objects": [
188 { "kind": "<kind>",
189 "version": { "major": 1, "minor": 0 },
190 "jsonFile": "<file>" },
191 { "...": "..." }
192 ],
193 "reply": {
194 "<kind>-v<major>": { "kind": "<kind>",
195 "version": { "major": 1, "minor": 0 },
196 "jsonFile": "<file>" },
197 "<unknown>": { "error": "unknown query file" },
198 "...": {},
199 "client-<client>": {
200 "<kind>-v<major>": { "kind": "<kind>",
201 "version": { "major": 1, "minor": 0 },
202 "jsonFile": "<file>" },
203 "<unknown>": { "error": "unknown query file" },
204 "...": {},
205 "query.json": {
206 "requests": [ {}, {}, {} ],
207 "responses": [
208 { "kind": "<kind>",
209 "version": { "major": 1, "minor": 0 },
210 "jsonFile": "<file>" },
211 { "error": "unknown query file" },
212 { "...": {} }
213 ],
214 "client": {}
215 }
216 }
217 }
218 }
219 The members are:
221 cmake A JSON object containing information about the instance of CMake
223 that generated the reply. It contains members:
224 version
226 A JSON object specifying the version of CMake with mem‐
227 bers:
228 major, minor, patch
230 Integer values specifying the major, minor, and
231 patch version components.
232 suffix A string specifying the version suffix, if any,
234 e.g. g0abc3.
235 string A string specifying the full version in the format
237 <major>.<minor>.<patch>[-<suffix>].
238 isDirty
240 A boolean indicating whether the version was built
241 from a version controlled source tree with local
242 modifications.
243 paths A JSON object specifying paths to things that come with
245 CMake. It has members for cmake, ctest, and cpack whose
246 values are JSON strings specifying the absolute path to
247 each tool, represented with forward slashes. It also has
248 a root member for the absolute path to the directory con‐
249 taining CMake resources like the Modules/ directory (see
250 CMAKE_ROOT).
251 generator
253 A JSON object describing the CMake generator used for the
254 build. It has members:
255 name A string specifying the name of the generator.
257 platform
259 If the generator supports CMAKE_GENERATOR_PLAT‐
260 FORM, this is a string specifying the generator
261 platform name.
262 objects
264 A JSON array listing all versions of all Object Kinds generated
265 as part of the reply. Each array entry is a v1 Reply File Ref‐
266 erence.
267 reply A JSON object mirroring the content of the query/ directory that
269 CMake loaded to produce the reply. The members are of the form
270 <kind>-v<major>
272 A member of this form appears for each of the v1 Shared
273 Stateless Query Files that CMake recognized as a request
274 for object kind <kind> with major version <major>. The
275 value is a v1 Reply File Reference to the corresponding
276 reply file for that object kind and version.
277 <unknown>
279 A member of this form appears for each of the v1 Shared
280 Stateless Query Files that CMake did not recognize. The
281 value is a JSON object with a single error member con‐
282 taining a string with an error message indicating that
283 the query file is unknown.
284 client-<client>
286 A member of this form appears for each client-owned
287 directory holding v1 Client Stateless Query Files. The
288 value is a JSON object mirroring the content of the
289 query/client-<client>/ directory. The members are of the
290 form:
291 <kind>-v<major>
293 A member of this form appears for each of the v1
294 Client Stateless Query Files that CMake recognized
295 as a request for object kind <kind> with major
296 version <major>. The value is a v1 Reply File
297 Reference to the corresponding reply file for that
298 object kind and version.
299 <unknown>
301 A member of this form appears for each of the v1
302 Client Stateless Query Files that CMake did not
303 recognize. The value is a JSON object with a sin‐
304 gle error member containing a string with an error
305 message indicating that the query file is unknown.
306 query.json
308 This member appears for clients using v1 Client
309 Stateful Query Files. If the query.json file
310 failed to read or parse as a JSON object, this
311 member is a JSON object with a single error member
312 containing a string with an error message. Other‐
313 wise, this member is a JSON object mirroring the
314 content of the query.json file. The members are:
315 client A copy of the query.json file client mem‐
317 ber, if it exists.
318 requests
320 A copy of the query.json file requests mem‐
321 ber, if it exists.
322 responses
324 If the query.json file requests member is
325 missing or invalid, this member is a JSON
326 object with a single error member contain‐
327 ing a string with an error message. Other‐
328 wise, this member contains a JSON array
329 with a response for each entry of the
330 requests array, in the same order. Each
331 response is
332 · a JSON object with a single error member
334 containing a string with an error mes‐
335 sage, or
336 · a v1 Reply File Reference to the corre‐
338 sponding reply file for the requested
339 object kind and selected version.
340 After reading the reply index file, clients may read the other v1 Reply
342 Files it references.
343 v1 Reply File Reference
345 The reply index file represents each reference to another reply file
346 using a JSON object with members:
347 kind A string specifying one of the Object Kinds.
349 version
351 A JSON object with members major and minor specifying integer
352 version components of the object kind.
353 jsonFile
355 A JSON string specifying a path relative to the reply index file
356 to another JSON file containing the object.
357 v1 Reply Files
359 Reply files containing specific Object Kinds are written by CMake. The
360 names of these files are unspecified and must not be interpreted by
361 clients. Clients must first read the v1 Reply Index File and and fol‐
362 low references to the names of the desired response objects.
363 Reply files (including the index file) will never be replaced by files
365 of the same name but different content. This allows a client to read
366 the files concurrently with a running CMake that may generate a new
367 reply. However, after generating a new reply CMake will attempt to
368 remove reply files from previous runs that it did not just write. If a
369 client attempts to read a reply file referenced by the index but finds
370 the file missing, that means a concurrent CMake has generated a new
371 reply. The client may simply start again by reading the new reply
372 index file.
373
375 The CMake file-based API reports semantic information about the build
376 system using the following kinds of JSON objects. Each kind of object
377 is versioned independently using semantic versioning with major and
378 minor components. Every kind of object has the form:
379 {
381 "kind": "<kind>",
382 "version": { "major": 1, "minor": 0 },
383 "...": {}
384 }
385 The kind member is a string specifying the object kind name. The ver‐
387 sion member is a JSON object with major and minor members specifying
388 integer components of the object kind’s version. Additional top-level
389 members are specific to each object kind.
390 Object Kind “codemodel”
392 The codemodel object kind describes the build system structure as mod‐
393 eled by CMake.
394 There is only one codemodel object major version, version 2. Version 1
396 does not exist to avoid confusion with that from cmake-server(7) mode.
397 “codemodel” version 2
399 codemodel object version 2 is a JSON object:
400 {
402 "kind": "codemodel",
403 "version": { "major": 2, "minor": 0 },
404 "paths": {
405 "source": "/path/to/top-level-source-dir",
406 "build": "/path/to/top-level-build-dir"
407 },
408 "configurations": [
409 {
410 "name": "Debug",
411 "directories": [
412 {
413 "source": ".",
414 "build": ".",
415 "childIndexes": [ 1 ],
416 "projectIndex": 0,
417 "targetIndexes": [ 0 ],
418 "hasInstallRule": true,
419 "minimumCMakeVersion": {
420 "string": "3.14"
421 }
422 },
423 {
424 "source": "sub",
425 "build": "sub",
426 "parentIndex": 0,
427 "projectIndex": 0,
428 "targetIndexes": [ 1 ],
429 "minimumCMakeVersion": {
430 "string": "3.14"
431 }
432 }
433 ],
434 "projects": [
435 {
436 "name": "MyProject",
437 "directoryIndexes": [ 0, 1 ],
438 "targetIndexes": [ 0, 1 ]
439 }
440 ],
441 "targets": [
442 {
443 "name": "MyExecutable",
444 "directoryIndex": 0,
445 "projectIndex": 0,
446 "jsonFile": "<file>"
447 },
448 {
449 "name": "MyLibrary",
450 "directoryIndex": 1,
451 "projectIndex": 0,
452 "jsonFile": "<file>"
453 }
454 ]
455 }
456 ]
457 }
458 The members specific to codemodel objects are:
460 paths A JSON object containing members:
462 source A string specifying the absolute path to the top-level
464 source directory, represented with forward slashes.
465 build A string specifying the absolute path to the top-level
467 build directory, represented with forward slashes.
468 configurations
470 A JSON array of entries corresponding to available build config‐
471 urations. On single-configuration generators there is one entry
472 for the value of the CMAKE_BUILD_TYPE variable. For multi-con‐
473 figuration generators there is an entry for each configuration
474 listed in the CMAKE_CONFIGURATION_TYPES variable. Each entry is
475 a JSON object containing members:
476 name A string specifying the name of the configuration, e.g.
478 Debug.
479 directories
481 A JSON array of entries each corresponding to a build
482 system directory whose source directory contains a CMake‐
483 Lists.txt file. The first entry corresponds to the
484 top-level directory. Each entry is a JSON object con‐
485 taining members:
486 source A string specifying the path to the source direc‐
488 tory, represented with forward slashes. If the
489 directory is inside the top-level source directory
490 then the path is specified relative to that direc‐
491 tory (with . for the top-level source directory
492 itself). Otherwise the path is absolute.
493 build A string specifying the path to the build direc‐
495 tory, represented with forward slashes. If the
496 directory is inside the top-level build directory
497 then the path is specified relative to that direc‐
498 tory (with . for the top-level build directory
499 itself). Otherwise the path is absolute.
500 parentIndex
502 Optional member that is present when the directory
503 is not top-level. The value is an unsigned inte‐
504 ger 0-based index of another entry in the main
505 directories array that corresponds to the parent
506 directory that added this directory as a subdirec‐
507 tory.
508 childIndexes
510 Optional member that is present when the directory
511 has subdirectories. The value is a JSON array of
512 entries corresponding to child directories created
513 by the add_subdirectory() or subdirs() command.
514 Each entry is an unsigned integer 0-based index of
515 another entry in the main directories array.
516 projectIndex
518 An unsigned integer 0-based index into the main
519 projects array indicating the build system project
520 to which the this directory belongs.
521 targetIndexes
523 Optional member that is present when the directory
524 itself has targets, excluding those belonging to
525 subdirectories. The value is a JSON array of
526 entries corresponding to the targets. Each entry
527 is an unsigned integer 0-based index into the main
528 targets array.
529 minimumCMakeVersion
531 Optional member present when a minimum required
532 version of CMake is known for the directory. This
533 is the <min> version given to the most local call
534 to the cmake_minimum_required(VERSION) command in
535 the directory itself or one of its ancestors. The
536 value is a JSON object with one member:
537 string A string specifying the minimum required
539 version in the format:
540 <major>.<minor>[.<patch>[.<tweak>]][<suffix>]
542 Each component is an unsigned integer and
544 the suffix may be an arbitrary string.
545 hasInstallRule
547 Optional member that is present with boolean value
548 true when the directory or one of its subdirecto‐
549 ries contains any install() rules, i.e. whether a
550 make install or equivalent rule is available.
551 projects
553 A JSON array of entries corresponding to the top-level
554 project and sub-projects defined in the build system.
555 Each (sub-)project corresponds to a source directory
556 whose CMakeLists.txt file calls the project() command
557 with a project name different from its parent directory.
558 The first entry corresponds to the top-level project.
559 Each entry is a JSON object containing members:
561 name A string specifying the name given to the
563 project() command.
564 parentIndex
566 Optional member that is present when the project
567 is not top-level. The value is an unsigned inte‐
568 ger 0-based index of another entry in the main
569 projects array that corresponds to the parent
570 project that added this project as a sub-project.
571 childIndexes
573 Optional member that is present when the project
574 has sub-projects. The value is a JSON array of
575 entries corresponding to the sub-projects. Each
576 entry is an unsigned integer 0-based index of
577 another entry in the main projects array.
578 directoryIndexes
580 A JSON array of entries corresponding to build
581 system directories that are part of the project.
582 The first entry corresponds to the top-level
583 directory of the project. Each entry is an
584 unsigned integer 0-based index into the main
585 directories array.
586 targetIndexes
588 Optional member that is present when the project
589 itself has targets, excluding those belonging to
590 sub-projects. The value is a JSON array of
591 entries corresponding to the targets. Each entry
592 is an unsigned integer 0-based index into the main
593 targets array.
594 targets
596 A JSON array of entries corresponding to the build system
597 targets. Such targets are created by calls to add_exe‐
598 cutable(), add_library(), and add_custom_target(),
599 excluding imported targets and interface libraries (which
600 do not generate any build rules). Each entry is a JSON
601 object containing members:
602 name A string specifying the target name.
604 id A string uniquely identifying the target. This
606 matches the id field in the file referenced by
607 jsonFile.
608 directoryIndex
610 An unsigned integer 0-based index into the main
611 directories array indicating the build system
612 directory in which the target is defined.
613 projectIndex
615 An unsigned integer 0-based index into the main
616 projects array indicating the build system project
617 in which the target is defined.
618 jsonFile
620 A JSON string specifying a path relative to the
621 codemodel file to another JSON file containing a
622 “codemodel” version 2 “target” object.
623 “codemodel” version 2 “target” object
625 A codemodel “target” object is referenced by a “codemodel” version 2
626 object’s targets array. Each “target” object is a JSON object with
627 members:
628 name A string specifying the logical name of the target.
630 id A string uniquely identifying the target. The format is unspec‐
632 ified and should not be interpreted by clients.
633 type A string specifying the type of the target. The value is one of
635 EXECUTABLE, STATIC_LIBRARY, SHARED_LIBRARY, MODULE_LIBRARY,
636 OBJECT_LIBRARY, or UTILITY.
637 backtrace
639 Optional member that is present when a CMake language backtrace
640 to the command in the source code that created the target is
641 available. The value is an unsigned integer 0-based index into
642 the backtraceGraph member’s nodes array.
643 folder Optional member that is present when the FOLDER target property
645 is set. The value is a JSON object with one member:
646 name A string specifying the name of the target folder.
648 paths A JSON object containing members:
650 source A string specifying the path to the target’s source
652 directory, represented with forward slashes. If the
653 directory is inside the top-level source directory then
654 the path is specified relative to that directory (with .
655 for the top-level source directory itself). Otherwise
656 the path is absolute.
657 build A string specifying the path to the target’s build direc‐
659 tory, represented with forward slashes. If the directory
660 is inside the top-level build directory then the path is
661 specified relative to that directory (with . for the
662 top-level build directory itself). Otherwise the path is
663 absolute.
664 nameOnDisk
666 Optional member that is present for executable and library tar‐
667 gets that are linked or archived into a single primary artifact.
668 The value is a string specifying the file name of that artifact
669 on disk.
670 artifacts
672 Optional member that is present for executable and library tar‐
673 gets that produce artifacts on disk meant for consumption by
674 dependents. The value is a JSON array of entries corresponding
675 to the artifacts. Each entry is a JSON object containing one
676 member:
677 path A string specifying the path to the file on disk, repre‐
679 sented with forward slashes. If the file is inside the
680 top-level build directory then the path is specified rel‐
681 ative to that directory. Otherwise the path is absolute.
682 isGeneratorProvided
684 Optional member that is present with boolean value true if the
685 target is provided by CMake’s build system generator rather than
686 by a command in the source code.
687 install
689 Optional member that is present when the target has an install()
690 rule. The value is a JSON object with members:
691 prefix A JSON object specifying the installation prefix. It has
693 one member:
694 path A string specifying the value of
696 CMAKE_INSTALL_PREFIX.
697 destinations
699 A JSON array of entries specifying an install destination
700 path. Each entry is a JSON object with members:
701 path A string specifying the install destination path.
703 The path may be absolute or relative to the
704 install prefix.
705 backtrace
707 Optional member that is present when a CMake lan‐
708 guage backtrace to the install() command invoca‐
709 tion that specified this destination is available.
710 The value is an unsigned integer 0-based index
711 into the backtraceGraph member’s nodes array.
712 link Optional member that is present for executables and shared
714 library targets that link into a runtime binary. The value is a
715 JSON object with members describing the link step:
716 language
718 A string specifying the language (e.g. C, CXX, Fortran)
719 of the toolchain is used to invoke the linker.
720 commandFragments
722 Optional member that is present when fragments of the
723 link command line invocation are available. The value is
724 a JSON array of entries specifying ordered fragments.
725 Each entry is a JSON object with members:
726 fragment
728 A string specifying a fragment of the link command
729 line invocation. The value is encoded in the
730 build system’s native shell format.
731 role A string specifying the role of the fragment’s
733 content:
734 · flags: link flags.
736 · libraries: link library file paths or flags.
738 · libraryPath: library search path flags.
740 · frameworkPath: macOS framework search path
742 flags.
743 lto Optional member that is present with boolean value true
745 when link-time optimization (a.k.a. interprocedural opti‐
746 mization or link-time code generation) is enabled.
747 sysroot
749 Optional member that is present when the CMAKE_SYS‐
750 ROOT_LINK or CMAKE_SYSROOT variable is defined. The
751 value is a JSON object with one member:
752 path A string specifying the absolute path to the sys‐
754 root, represented with forward slashes.
755 archive
757 Optional member that is present for static library targets. The
758 value is a JSON object with members describing the archive step:
759 commandFragments
761 Optional member that is present when fragments of the
762 archiver command line invocation are available. The
763 value is a JSON array of entries specifying the frag‐
764 ments. Each entry is a JSON object with members:
765 fragment
767 A string specifying a fragment of the archiver
768 command line invocation. The value is encoded in
769 the build system’s native shell format.
770 role A string specifying the role of the fragment’s
772 content:
773 · flags: archiver flags.
775 lto Optional member that is present with boolean value true
777 when link-time optimization (a.k.a. interprocedural opti‐
778 mization or link-time code generation) is enabled.
779 dependencies
781 Optional member that is present when the target depends on other
782 targets. The value is a JSON array of entries corresponding to
783 the dependencies. Each entry is a JSON object with members:
784 id A string uniquely identifying the target on which this
786 target depends. This matches the main id member of the
787 other target.
788 backtrace
790 Optional member that is present when a CMake language
791 backtrace to the add_dependencies(), tar‐
792 get_link_libraries(), or other command invocation that
793 created this dependency is available. The value is an
794 unsigned integer 0-based index into the backtraceGraph
795 member’s nodes array.
796 sources
798 A JSON array of entries corresponding to the target’s source
799 files. Each entry is a JSON object with members:
800 path A string specifying the path to the source file on disk,
802 represented with forward slashes. If the file is inside
803 the top-level source directory then the path is specified
804 relative to that directory. Otherwise the path is abso‐
805 lute.
806 compileGroupIndex
808 Optional member that is present when the source is com‐
809 piled. The value is an unsigned integer 0-based index
810 into the compileGroups array.
811 sourceGroupIndex
813 Optional member that is present when the source is part
814 of a source group either via the source_group() command
815 or by default. The value is an unsigned integer 0-based
816 index into the sourceGroups array.
817 isGenerated
819 Optional member that is present with boolean value true
820 if the source is GENERATED.
821 backtrace
823 Optional member that is present when a CMake language
824 backtrace to the target_sources(), add_executable(),
825 add_library(), add_custom_target(), or other command
826 invocation that added this source to the target is avail‐
827 able. The value is an unsigned integer 0-based index
828 into the backtraceGraph member’s nodes array.
829 sourceGroups
831 Optional member that is present when sources are grouped
832 together by the source_group() command or by default. The value
833 is a JSON array of entries corresponding to the groups. Each
834 entry is a JSON object with members:
835 name A string specifying the name of the source group.
837 sourceIndexes
839 A JSON array listing the sources belonging to the group.
840 Each entry is an unsigned integer 0-based index into the
841 main sources array for the target.
842 compileGroups
844 Optional member that is present when the target has sources that
845 compile. The value is a JSON array of entries corresponding to
846 groups of sources that all compile with the same settings. Each
847 entry is a JSON object with members:
848 sourceIndexes
850 A JSON array listing the sources belonging to the group.
851 Each entry is an unsigned integer 0-based index into the
852 main sources array for the target.
853 language
855 A string specifying the language (e.g. C, CXX, Fortran)
856 of the toolchain is used to compile the source file.
857 compileCommandFragments
859 Optional member that is present when fragments of the
860 compiler command line invocation are available. The
861 value is a JSON array of entries specifying ordered frag‐
862 ments. Each entry is a JSON object with one member:
863 fragment
865 A string specifying a fragment of the compile com‐
866 mand line invocation. The value is encoded in the
867 build system’s native shell format.
868 includes
870 Optional member that is present when there are include
871 directories. The value is a JSON array with an entry for
872 each directory. Each entry is a JSON object with mem‐
873 bers:
874 path A string specifying the path to the include direc‐
876 tory, represented with forward slashes.
877 isSystem
879 Optional member that is present with boolean value
880 true if the include directory is marked as a sys‐
881 tem include directory.
882 backtrace
884 Optional member that is present when a CMake lan‐
885 guage backtrace to the target_include_directo‐
886 ries() or other command invocation that added this
887 include directory is available. The value is an
888 unsigned integer 0-based index into the backtrace‐
889 Graph member’s nodes array.
890 defines
892 Optional member that is present when there are preproces‐
893 sor definitions. The value is a JSON array with an entry
894 for each definition. Each entry is a JSON object with
895 members:
896 define A string specifying the preprocessor definition in
898 the format <name>[=<value>], e.g. DEF or DEF=1.
899 backtrace
901 Optional member that is present when a CMake lan‐
902 guage backtrace to the target_compile_defini‐
903 tions() or other command invocation that added
904 this preprocessor definition is available. The
905 value is an unsigned integer 0-based index into
906 the backtraceGraph member’s nodes array.
907 sysroot
909 Optional member that is present when the CMAKE_SYS‐
910 ROOT_COMPILE or CMAKE_SYSROOT variable is defined. The
911 value is a JSON object with one member:
912 path A string specifying the absolute path to the sys‐
914 root, represented with forward slashes.
915 backtraceGraph
917 A JSON object describing the graph of backtraces whose nodes are
918 referenced from backtrace members elsewhere. The members are:
919 nodes A JSON array listing nodes in the backtrace graph. Each
921 entry is a JSON object with members:
922 file An unsigned integer 0-based index into the back‐
924 trace files array.
925 line An optional member present when the node repre‐
927 sents a line within the file. The value is an
928 unsigned integer 1-based line number.
929 command
931 An optional member present when the node repre‐
932 sents a command invocation within the file. The
933 value is an unsigned integer 0-based index into
934 the backtrace commands array.
935 parent An optional member present when the node is not
937 the bottom of the call stack. The value is an
938 unsigned integer 0-based index of another entry in
939 the backtrace nodes array.
940 commands
942 A JSON array listing command names referenced by back‐
943 trace nodes. Each entry is a string specifying a command
944 name.
945 files A JSON array listing CMake language files referenced by
947 backtrace nodes. Each entry is a string specifying the
948 path to a file, represented with forward slashes. If the
949 file is inside the top-level source directory then the
950 path is specified relative to that directory. Otherwise
951 the path is absolute.
952 Object Kind “cache”
954 The cache object kind lists cache entries. These are the CMake Lan‐
955 guage Variables stored in the persistent cache (CMakeCache.txt) for the
956 build tree.
957 There is only one cache object major version, version 2. Version 1
959 does not exist to avoid confusion with that from cmake-server(7) mode.
960 “cache” version 2
962 cache object version 2 is a JSON object:
963 {
965 "kind": "cache",
966 "version": { "major": 2, "minor": 0 },
967 "entries": [
968 {
969 "name": "BUILD_SHARED_LIBS",
970 "value": "ON",
971 "type": "BOOL",
972 "properties": [
973 {
974 "name": "HELPSTRING",
975 "value": "Build shared libraries"
976 }
977 ]
978 },
979 {
980 "name": "CMAKE_GENERATOR",
981 "value": "Unix Makefiles",
982 "type": "INTERNAL",
983 "properties": [
984 {
985 "name": "HELPSTRING",
986 "value": "Name of generator."
987 }
988 ]
989 }
990 ]
991 }
992 The members specific to cache objects are:
994 entries
996 A JSON array whose entries are each a JSON object specifying a
997 cache entry. The members of each entry are:
998 name A string specifying the name of the entry.
1000 value A string specifying the value of the entry.
1002 type A string specifying the type of the entry used by
1004 cmake-gui(1) to choose a widget for editing.
1005 properties
1007 A JSON array of entries specifying associated cache entry
1008 properties. Each entry is a JSON object containing mem‐
1009 bers:
1010 name A string specifying the name of the cache entry
1012 property.
1013 value A string specifying the value of the cache entry
1015 property.
1016 Object Kind “cmakeFiles”
1018 The cmakeFiles object kind lists files used by CMake while configuring
1019 and generating the build system. These include the CMakeLists.txt
1020 files as well as included .cmake files.
1021 There is only one cmakeFiles object major version, version 1.
1023 “cmakeFiles” version 1
1025 cmakeFiles object version 1 is a JSON object:
1026 {
1028 "kind": "cmakeFiles",
1029 "version": { "major": 1, "minor": 0 },
1030 "paths": {
1031 "build": "/path/to/top-level-build-dir",
1032 "source": "/path/to/top-level-source-dir"
1033 },
1034 "inputs": [
1035 {
1036 "path": "CMakeLists.txt"
1037 },
1038 {
1039 "isGenerated": true,
1040 "path": "/path/to/top-level-build-dir/.../CMakeSystem.cmake"
1041 },
1042 {
1043 "isExternal": true,
1044 "path": "/path/to/external/third-party/module.cmake"
1045 },
1046 {
1047 "isCMake": true,
1048 "isExternal": true,
1049 "path": "/path/to/cmake/Modules/CMakeGenericSystem.cmake"
1050 }
1051 ]
1052 }
1053 The members specific to cmakeFiles objects are:
1055 paths A JSON object containing members:
1057 source A string specifying the absolute path to the top-level
1059 source directory, represented with forward slashes.
1060 build A string specifying the absolute path to the top-level
1062 build directory, represented with forward slashes.
1063 inputs A JSON array whose entries are each a JSON object specifying an
1065 input file used by CMake when configuring and generating the
1066 build system. The members of each entry are:
1067 path A string specifying the path to an input file to CMake,
1069 represented with forward slashes. If the file is inside
1070 the top-level source directory then the path is specified
1071 relative to that directory. Otherwise the path is abso‐
1072 lute.
1073 isGenerated
1075 Optional member that is present with boolean value true
1076 if the path specifies a file that is under the top-level
1077 build directory and the build is out-of-source. This
1078 member is not available on in-source builds.
1079 isExternal
1081 Optional member that is present with boolean value true
1082 if the path specifies a file that is not under the
1083 top-level source or build directories.
1084 isCMake
1086 Optional member that is present with boolean value true
1087 if the path specifies a file in the CMake installation.
1088
1090 2000-2019 Kitware, Inc. and Contributors
10913.16.1 Dec 14, 2019 CMAKE-FILE-API(7)