1CMAKE-FILE-API(7)                    CMake                   CMAKE-FILE-API(7)
2
3
4

NAME

6       cmake-file-api - CMake File-Based API
7

INTRODUCTION

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
16       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

API V1

23       API v1 is housed in the <build>/.cmake/api/v1/ directory.  It  has  the
24       following subdirectories:
25
26       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
30       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
35              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
39   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
44       Clients may create shared requests  by  creating  empty  files  in  the
45       v1/query/ directory.  The form is:
46
47          <build>/.cmake/api/v1/query/<kind>-v<major>
48
49       where  <kind> is one of the Object Kinds, -v is literal, and <major> is
50       the major version number.
51
52       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
56   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
61       Clients  may  create  owned  requests  by  creating  empty   files   in
62       client-specific query subdirectories.  The form is:
63
64          <build>/.cmake/api/v1/query/client-<client>/<kind>-v<major>
65
66       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
71       Files of this form are stateless queries owned by the client  <client>.
72       The owning client may remove them at any time.
73
74   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
79       Clients  may create owned stateful queries by creating query.json files
80       in client-specific query subdirectories.  The form is:
81
82          <build>/.cmake/api/v1/query/client-<client>/query.json
83
84       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
88       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
95       A query.json file must contain a JSON object:
96
97          {
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
109       The members are:
110
111       requests
112              A  JSON array containing zero or more requests.  Each request is
113              a JSON object with members:
114
115              kind   Specifies one of the Object Kinds to be included  in  the
116                     reply.
117
118              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
124                     • a JSON integer specifying a (non-negative)  major  ver‐
125                       sion number, or
126
127                     • a  JSON  object containing major and (optionally) minor
128                       members specifying non-negative integer version  compo‐
129                       nents, or
130
131                     • a JSON array whose elements are each one of the above.
132
133              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
139              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
147       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
152       Other query.json top-level members are reserved  for  future  use.   If
153       present they are ignored for forward compatibility.
154
155   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
161          <build>/.cmake/api/v1/reply/index-<unspecified>.json
162
163       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
169       The reply index file contains a JSON object:
170
171          {
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
221       The members are:
222
223       cmake  A JSON object containing information about the instance of CMake
224              that generated the reply.  It contains members:
225
226              version
227                     A  JSON  object specifying the version of CMake with mem‐
228                     bers:
229
230                     major, minor, patch
231                            Integer values specifying the  major,  minor,  and
232                            patch version components.
233
234                     suffix A  string  specifying  the version suffix, if any,
235                            e.g. g0abc3.
236
237                     string A string specifying the full version in the format
238                            <major>.<minor>.<patch>[-<suffix>].
239
240                     isDirty
241                            A boolean indicating whether the version was built
242                            from a version controlled source tree  with  local
243                            modifications.
244
245              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
253              generator
254                     A JSON object describing the CMake generator used for the
255                     build.  It has members:
256
257                     multiConfig
258                            A boolean specifying whether  the  generator  sup‐
259                            ports multiple output configurations.
260
261                     name   A string specifying the name of the generator.
262
263                     platform
264                            If  the  generator  supports CMAKE_GENERATOR_PLAT‐
265                            FORM, this is a string  specifying  the  generator
266                            platform name.
267
268       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
273       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
276              <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
283              <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
290              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
297                     <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
305                     <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
312                     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
321                            client A  copy  of the query.json file client mem‐
322                                   ber, if it exists.
323
324                            requests
325                                   A copy of the query.json file requests mem‐
326                                   ber, if it exists.
327
328                            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
338                                   • a JSON object with a single error  member
339                                     containing  a  string  with an error mes‐
340                                     sage, or
341
342                                   • a v1 Reply File Reference to  the  corre‐
343                                     sponding reply file for the requested ob‐
344                                     ject kind and selected version.
345
346       After reading the reply index file, clients may read the other v1 Reply
347       Files it references.
348
349   v1 Reply File Reference
350       The  reply  index  file represents each reference to another reply file
351       using a JSON object with members:
352
353       kind   A string specifying one of the Object Kinds.
354
355       version
356              A JSON object with members major and  minor  specifying  integer
357              version components of the object kind.
358
359       jsonFile
360              A JSON string specifying a path relative to the reply index file
361              to another JSON file containing the object.
362
363   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
369       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

OBJECT KINDS

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
385          {
386            "kind": "<kind>",
387            "version": { "major": 1, "minor": 0 },
388            "...": {}
389          }
390
391       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
396   Object Kind codemodel
397       The  codemodel object kind describes the build system structure as mod‐
398       eled by CMake.
399
400       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
403   codemodel version 2
404       codemodel object version 2 is a JSON object:
405
406          {
407            "kind": "codemodel",
408            "version": { "major": 2, "minor": 2 },
409            "paths": {
410              "source": "/path/to/top-level-source-dir",
411              "build": "/path/to/top-level-build-dir"
412            },
413            "configurations": [
414              {
415                "name": "Debug",
416                "directories": [
417                  {
418                    "source": ".",
419                    "build": ".",
420                    "childIndexes": [ 1 ],
421                    "projectIndex": 0,
422                    "targetIndexes": [ 0 ],
423                    "hasInstallRule": true,
424                    "minimumCMakeVersion": {
425                      "string": "3.14"
426                    }
427                  },
428                  {
429                    "source": "sub",
430                    "build": "sub",
431                    "parentIndex": 0,
432                    "projectIndex": 0,
433                    "targetIndexes": [ 1 ],
434                    "minimumCMakeVersion": {
435                      "string": "3.14"
436                    }
437                  }
438                ],
439                "projects": [
440                  {
441                    "name": "MyProject",
442                    "directoryIndexes": [ 0, 1 ],
443                    "targetIndexes": [ 0, 1 ]
444                  }
445                ],
446                "targets": [
447                  {
448                    "name": "MyExecutable",
449                    "directoryIndex": 0,
450                    "projectIndex": 0,
451                    "jsonFile": "<file>"
452                  },
453                  {
454                    "name": "MyLibrary",
455                    "directoryIndex": 1,
456                    "projectIndex": 0,
457                    "jsonFile": "<file>"
458                  }
459                ]
460              }
461            ]
462          }
463
464       The members specific to codemodel objects are:
465
466       paths  A JSON object containing members:
467
468              source A  string  specifying  the absolute path to the top-level
469                     source directory, represented with forward slashes.
470
471              build  A string specifying the absolute path  to  the  top-level
472                     build directory, represented with forward slashes.
473
474       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
482              name   A string specifying the name of the  configuration,  e.g.
483                     Debug.
484
485              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
492                     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
499                     build  A string specifying the path to the  build  direc‐
500                            tory,  represented  with  forward slashes.  If the
501                            directory is inside the top-level build  directory
502                            then the path is specified relative to that direc‐
503                            tory (with . for the top-level build directory it‐
504                            self).  Otherwise the path is absolute.
505
506                     parentIndex
507                            Optional member that is present when the directory
508                            is not top-level.  The value is an unsigned  inte‐
509                            ger 0-based index of another entry in the main di‐
510                            rectories array that corresponds to the parent di‐
511                            rectory  that  added this directory as a subdirec‐
512                            tory.
513
514                     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
522                     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
527                     targetIndexes
528                            Optional member that is present when the directory
529                            itself has targets, excluding those  belonging  to
530                            subdirectories.   The value is a JSON array of en‐
531                            tries corresponding to the targets.  Each entry is
532                            an  unsigned  integer  0-based index into the main
533                            targets array.
534
535                     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
543                            string A  string  specifying  the minimum required
544                                   version in the format:
545
546                                      <major>.<minor>[.<patch>[.<tweak>]][<suffix>]
547
548                                   Each component is an unsigned  integer  and
549                                   the suffix may be an arbitrary string.
550
551                     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
557              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
565                     Each entry is a JSON object containing members:
566
567                     name   A   string   specifying  the  name  given  to  the
568                            project() command.
569
570                     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
577                     childIndexes
578                            Optional member that is present when  the  project
579                            has  sub-projects.   The  value is a JSON array of
580                            entries corresponding to the  sub-projects.   Each
581                            entry  is an unsigned integer 0-based index of an‐
582                            other entry in the main projects array.
583
584                     directoryIndexes
585                            A JSON array of  entries  corresponding  to  build
586                            system  directories  that are part of the project.
587                            The first entry corresponds to the  top-level  di‐
588                            rectory of the project.  Each entry is an unsigned
589                            integer 0-based index into  the  main  directories
590                            array.
591
592                     targetIndexes
593                            Optional  member  that is present when the project
594                            itself has targets, excluding those  belonging  to
595                            sub-projects.   The  value  is a JSON array of en‐
596                            tries corresponding to the targets.  Each entry is
597                            an  unsigned  integer  0-based index into the main
598                            targets array.
599
600              targets
601                     A JSON array of entries corresponding to the build system
602                     targets.   Such  targets are created by calls to add_exe‐
603                     cutable(), add_library(),  and  add_custom_target(),  ex‐
604                     cluding  imported  targets and interface libraries (which
605                     do not generate any build rules).  Each entry is  a  JSON
606                     object containing members:
607
608                     name   A string specifying the target name.
609
610                     id     A  string  uniquely  identifying the target.  This
611                            matches the id field in  the  file  referenced  by
612                            jsonFile.
613
614                     directoryIndex
615                            An  unsigned  integer  0-based index into the main
616                            directories array indicating the build system  di‐
617                            rectory in which the target is defined.
618
619                     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
624                     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
629   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
634       name   A string specifying the logical name of the target.
635
636       id     A string uniquely identifying the target.  The format is unspec‐
637              ified and should not be interpreted by clients.
638
639       type   A string specifying the type of the target.  The value is one of
640              EXECUTABLE,  STATIC_LIBRARY, SHARED_LIBRARY, MODULE_LIBRARY, OB‐
641              JECT_LIBRARY, INTERFACE_LIBRARY, or UTILITY.
642
643       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
649       folder Optional  member that is present when the FOLDER target property
650              is set.  The value is a JSON object with one member:
651
652              name   A string specifying the name of the target folder.
653
654       paths  A JSON object containing members:
655
656              source A string specifying the path to the target's  source  di‐
657                     rectory, represented with forward slashes.  If the direc‐
658                     tory is inside the top-level source  directory  then  the
659                     path  is specified relative to that directory (with . for
660                     the top-level source directory  itself).   Otherwise  the
661                     path is absolute.
662
663              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
670       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
676       artifacts
677              Optional  member that is present for executable and library tar‐
678              gets that produce artifacts on disk meant for consumption by de‐
679              pendents.  The value is a JSON array of entries corresponding to
680              the artifacts.  Each entry is a JSON object containing one  mem‐
681              ber:
682
683              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
688       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
693       install
694              Optional member that is present when the target has an install()
695              rule.  The value is a JSON object with members:
696
697              prefix A JSON object specifying the installation prefix.  It has
698                     one member:
699
700                     path   A  string  specifying  the  value   of   CMAKE_IN‐
701                            STALL_PREFIX.
702
703              destinations
704                     A JSON array of entries specifying an install destination
705                     path.  Each entry is a JSON object with members:
706
707                     path   A string specifying the install destination  path.
708                            The  path  may  be absolute or relative to the in‐
709                            stall prefix.
710
711                     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
718       link   Optional member that is present for executables and  shared  li‐
719              brary  targets  that link into a runtime binary.  The value is a
720              JSON object with members describing the link step:
721
722              language
723                     A string specifying the language (e.g. C,  CXX,  Fortran)
724                     of the toolchain is used to invoke the linker.
725
726              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
732                     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
737                     role   A string specifying the  role  of  the  fragment's
738                            content:
739
740flags: link flags.
741
742libraries: link library file paths or flags.
743
744libraryPath: library search path flags.
745
746frameworkPath:   macOS   framework  search  path
747                              flags.
748
749              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
753              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
758                     path   A string specifying the absolute path to the  sys‐
759                            root, represented with forward slashes.
760
761       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
765              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
771                     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
776                     role   A  string  specifying  the  role of the fragment's
777                            content:
778
779flags: archiver flags.
780
781              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
785       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
790              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
794              backtrace
795                     Optional member that is present  when  a  CMake  language
796                     backtrace   to  the  add_dependencies(),  target_link_li‐
797                     braries(), or other command invocation that created  this
798                     dependency  is available.  The value is an unsigned inte‐
799                     ger 0-based index into the backtraceGraph member's  nodes
800                     array.
801
802       sources
803              A  JSON  array  of  entries corresponding to the target's source
804              files.  Each entry is a JSON object with members:
805
806              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
812              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
817              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
823              isGenerated
824                     Optional  member  that is present with boolean value true
825                     if the source is GENERATED.
826
827              backtrace
828                     Optional member that is present  when  a  CMake  language
829                     backtrace   to  the  target_sources(),  add_executable(),
830                     add_library(), add_custom_target(), or other command  in‐
831                     vocation  that  added this source to the target is avail‐
832                     able.  The value is an  unsigned  integer  0-based  index
833                     into the backtraceGraph member's nodes array.
834
835       sourceGroups
836              Optional  member  that  is  present when sources are grouped to‐
837              gether by the source_group() command or by default.   The  value
838              is  a  JSON  array of entries corresponding to the groups.  Each
839              entry is a JSON object with members:
840
841              name   A string specifying the name of the source group.
842
843              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
848       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
854              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
859              language
860                     A  string  specifying the language (e.g. C, CXX, Fortran)
861                     of the toolchain is used to compile the source file.
862
863              languageStandard
864                     Optional member that is present when the  language  stan‐
865                     dard is set explicitly (e.g. via CXX_STANDARD) or implic‐
866                     itly by compile features.  Each entry is  a  JSON  object
867                     with two members:
868
869                     backtraces
870                            Optional  member that is present when a CMake lan‐
871                            guage backtrace to the <LANG>_STANDARD setting  is
872                            available.   If  the language standard was set im‐
873                            plicitly by compile features those are used as the
874                            backtrace(s).   It's possible for multiple compile
875                            features to require the same language standard  so
876                            there could be multiple backtraces. The value is a
877                            JSON array with each entry being an unsigned inte‐
878                            ger 0-based index into the backtraceGraph member's
879                            nodes array.
880
881                     standard
882                            String representing the language standard.
883
884                     This field was added in codemodel version 2.2.
885
886              compileCommandFragments
887                     Optional member that is present  when  fragments  of  the
888                     compiler  command  line  invocation  are  available.  The
889                     value is a JSON array of entries specifying ordered frag‐
890                     ments.  Each entry is a JSON object with one member:
891
892                     fragment
893                            A string specifying a fragment of the compile com‐
894                            mand line invocation.  The value is encoded in the
895                            build system's native shell format.
896
897              includes
898                     Optional  member  that  is present when there are include
899                     directories.  The value is a JSON array with an entry for
900                     each  directory.   Each  entry is a JSON object with mem‐
901                     bers:
902
903                     path   A string specifying the path to the include direc‐
904                            tory, represented with forward slashes.
905
906                     isSystem
907                            Optional member that is present with boolean value
908                            true if the include directory is marked as a  sys‐
909                            tem include directory.
910
911                     backtrace
912                            Optional  member that is present when a CMake lan‐
913                            guage  backtrace  to  the  target_include_directo‐
914                            ries() or other command invocation that added this
915                            include directory is available.  The value  is  an
916                            unsigned integer 0-based index into the backtrace‐
917                            Graph member's nodes array.
918
919              precompileHeaders
920                     Optional  member  that  is  present  when  target_precom‐
921                     pile_headers()  or  other command invocations set PRECOM‐
922                     PILE_HEADERS on the target.  The value is  a  JSON  array
923                     with  an entry for each header.  Each entry is a JSON ob‐
924                     ject with members:
925
926                     header Full path to the precompile header file.
927
928                     backtrace
929                            Optional member that is present when a CMake  lan‐
930                            guage backtrace to the target_precompile_headers()
931                            or other command invocation that added  this  pre‐
932                            compiled header is available.  The value is an un‐
933                            signed integer 0-based index into  the  backtrace‐
934                            Graph member's nodes array.
935
936                     This field was added in codemodel version 2.1.
937
938              defines
939                     Optional member that is present when there are preproces‐
940                     sor definitions.  The value is a JSON array with an entry
941                     for  each  definition.   Each entry is a JSON object with
942                     members:
943
944                     define A string specifying the preprocessor definition in
945                            the format <name>[=<value>], e.g. DEF or DEF=1.
946
947                     backtrace
948                            Optional  member that is present when a CMake lan‐
949                            guage  backtrace  to  the   target_compile_defini‐
950                            tions()  or  other  command  invocation that added
951                            this preprocessor definition  is  available.   The
952                            value  is  an  unsigned integer 0-based index into
953                            the backtraceGraph member's nodes array.
954
955              sysroot
956                     Optional member  that  is  present  when  the  CMAKE_SYS‐
957                     ROOT_COMPILE  or  CMAKE_SYSROOT variable is defined.  The
958                     value is a JSON object with one member:
959
960                     path   A string specifying the absolute path to the  sys‐
961                            root, represented with forward slashes.
962
963       backtraceGraph
964              A JSON object describing the graph of backtraces whose nodes are
965              referenced from backtrace members elsewhere.  The members are:
966
967              nodes  A JSON array listing nodes in the backtrace graph.   Each
968                     entry is a JSON object with members:
969
970                     file   An  unsigned  integer 0-based index into the back‐
971                            trace files array.
972
973                     line   An optional member present when  the  node  repre‐
974                            sents a line within the file.  The value is an un‐
975                            signed integer 1-based line number.
976
977                     command
978                            An optional member present when  the  node  repre‐
979                            sents  a  command invocation within the file.  The
980                            value is an unsigned integer  0-based  index  into
981                            the backtrace commands array.
982
983                     parent An  optional  member  present when the node is not
984                            the bottom of the call stack.  The value is an un‐
985                            signed  integer  0-based index of another entry in
986                            the backtrace nodes array.
987
988              commands
989                     A JSON array listing command names  referenced  by  back‐
990                     trace nodes.  Each entry is a string specifying a command
991                     name.
992
993              files  A JSON array listing CMake language files  referenced  by
994                     backtrace  nodes.   Each entry is a string specifying the
995                     path to a file, represented with forward slashes.  If the
996                     file  is  inside  the top-level source directory then the
997                     path is specified relative to that directory.   Otherwise
998                     the path is absolute.
999
1000   Object Kind cache
1001       The  cache  object  kind lists cache entries.  These are the CMake Lan‐
1002       guage Variables stored in the persistent cache (CMakeCache.txt) for the
1003       build tree.
1004
1005       There  is  only  one  cache object major version, version 2.  Version 1
1006       does not exist to avoid confusion with that from cmake-server(7) mode.
1007
1008   cache version 2
1009       cache object version 2 is a JSON object:
1010
1011          {
1012            "kind": "cache",
1013            "version": { "major": 2, "minor": 0 },
1014            "entries": [
1015              {
1016                "name": "BUILD_SHARED_LIBS",
1017                "value": "ON",
1018                "type": "BOOL",
1019                "properties": [
1020                  {
1021                    "name": "HELPSTRING",
1022                    "value": "Build shared libraries"
1023                  }
1024                ]
1025              },
1026              {
1027                "name": "CMAKE_GENERATOR",
1028                "value": "Unix Makefiles",
1029                "type": "INTERNAL",
1030                "properties": [
1031                  {
1032                    "name": "HELPSTRING",
1033                    "value": "Name of generator."
1034                  }
1035                ]
1036              }
1037            ]
1038          }
1039
1040       The members specific to cache objects are:
1041
1042       entries
1043              A JSON array whose entries are each a JSON object  specifying  a
1044              cache entry.  The members of each entry are:
1045
1046              name   A string specifying the name of the entry.
1047
1048              value  A string specifying the value of the entry.
1049
1050              type   A  string  specifying  the  type  of  the  entry  used by
1051                     cmake-gui(1) to choose a widget for editing.
1052
1053              properties
1054                     A JSON array of entries specifying associated cache entry
1055                     properties.   Each entry is a JSON object containing mem‐
1056                     bers:
1057
1058                     name   A string specifying the name of  the  cache  entry
1059                            property.
1060
1061                     value  A  string  specifying the value of the cache entry
1062                            property.
1063
1064   Object Kind cmakeFiles
1065       The cmakeFiles object kind lists files used by CMake while  configuring
1066       and  generating  the  build  system.   These include the CMakeLists.txt
1067       files as well as included .cmake files.
1068
1069       There is only one cmakeFiles object major version, version 1.
1070
1071   cmakeFiles version 1
1072       cmakeFiles object version 1 is a JSON object:
1073
1074          {
1075            "kind": "cmakeFiles",
1076            "version": { "major": 1, "minor": 0 },
1077            "paths": {
1078              "build": "/path/to/top-level-build-dir",
1079              "source": "/path/to/top-level-source-dir"
1080            },
1081            "inputs": [
1082              {
1083                "path": "CMakeLists.txt"
1084              },
1085              {
1086                "isGenerated": true,
1087                "path": "/path/to/top-level-build-dir/.../CMakeSystem.cmake"
1088              },
1089              {
1090                "isExternal": true,
1091                "path": "/path/to/external/third-party/module.cmake"
1092              },
1093              {
1094                "isCMake": true,
1095                "isExternal": true,
1096                "path": "/path/to/cmake/Modules/CMakeGenericSystem.cmake"
1097              }
1098            ]
1099          }
1100
1101       The members specific to cmakeFiles objects are:
1102
1103       paths  A JSON object containing members:
1104
1105              source A string specifying the absolute path  to  the  top-level
1106                     source directory, represented with forward slashes.
1107
1108              build  A  string  specifying  the absolute path to the top-level
1109                     build directory, represented with forward slashes.
1110
1111       inputs A JSON array whose entries are each a JSON object specifying  an
1112              input  file  used  by  CMake when configuring and generating the
1113              build system.  The members of each entry are:
1114
1115              path   A string specifying the path to an input file  to  CMake,
1116                     represented  with forward slashes.  If the file is inside
1117                     the top-level source directory then the path is specified
1118                     relative  to that directory.  Otherwise the path is abso‐
1119                     lute.
1120
1121              isGenerated
1122                     Optional member that is present with boolean  value  true
1123                     if  the path specifies a file that is under the top-level
1124                     build directory and the  build  is  out-of-source.   This
1125                     member is not available on in-source builds.
1126
1127              isExternal
1128                     Optional  member  that is present with boolean value true
1129                     if the path specifies  a  file  that  is  not  under  the
1130                     top-level source or build directories.
1131
1132              isCMake
1133                     Optional  member  that is present with boolean value true
1134                     if the path specifies a file in the CMake installation.
1135
1136   Object Kind toolchains
1137       The toolchains object kind lists properties of the toolchains used dur‐
1138       ing the build.  These include the language, compiler path, ID, and ver‐
1139       sion.
1140
1141       There is only one toolchains object major version, version 1.
1142
1143   toolchains version 1
1144       toolchains object version 1 is a JSON object:
1145
1146          {
1147            "kind": "toolchains",
1148            "version": { "major": 1, "minor": 0 },
1149            "toolchains": [
1150              {
1151                "language": "C",
1152                "compiler": {
1153                  "path": "/usr/bin/cc",
1154                  "id": "GNU",
1155                  "version": "9.3.0",
1156                  "implicit": {
1157                    "includeDirectories": [
1158                      "/usr/lib/gcc/x86_64-linux-gnu/9/include",
1159                      "/usr/local/include",
1160                      "/usr/include/x86_64-linux-gnu",
1161                      "/usr/include"
1162                    ],
1163                    "linkDirectories": [
1164                      "/usr/lib/gcc/x86_64-linux-gnu/9",
1165                      "/usr/lib/x86_64-linux-gnu",
1166                      "/usr/lib",
1167                      "/lib/x86_64-linux-gnu",
1168                      "/lib"
1169                    ],
1170                    "linkFrameworkDirectories": [],
1171                    "linkLibraries": [ "gcc", "gcc_s", "c", "gcc", "gcc_s" ]
1172                  }
1173                },
1174                "sourceFileExtensions": [ "c", "m" ]
1175              },
1176              {
1177                "language": "CXX",
1178                "compiler": {
1179                  "path": "/usr/bin/c++",
1180                  "id": "GNU",
1181                  "version": "9.3.0",
1182                  "implicit": {
1183                    "includeDirectories": [
1184                      "/usr/include/c++/9",
1185                      "/usr/include/x86_64-linux-gnu/c++/9",
1186                      "/usr/include/c++/9/backward",
1187                      "/usr/lib/gcc/x86_64-linux-gnu/9/include",
1188                      "/usr/local/include",
1189                      "/usr/include/x86_64-linux-gnu",
1190                      "/usr/include"
1191                    ],
1192                    "linkDirectories": [
1193                      "/usr/lib/gcc/x86_64-linux-gnu/9",
1194                      "/usr/lib/x86_64-linux-gnu",
1195                      "/usr/lib",
1196                      "/lib/x86_64-linux-gnu",
1197                      "/lib"
1198                    ],
1199                    "linkFrameworkDirectories": [],
1200                    "linkLibraries": [
1201                      "stdc++", "m", "gcc_s", "gcc", "c", "gcc_s", "gcc"
1202                    ]
1203                  }
1204                },
1205                "sourceFileExtensions": [
1206                  "C", "M", "c++", "cc", "cpp", "cxx", "mm", "CPP"
1207                ]
1208              }
1209            ]
1210          }
1211
1212       The members specific to toolchains objects are:
1213
1214       toolchains
1215              A JSON array whose entries are each a JSON object  specifying  a
1216              toolchain  associated with a particular language. The members of
1217              each entry are:
1218
1219              language
1220                     A JSON string specifying the toolchain language,  like  C
1221                     or  CXX.  Language  names  are the same as langauge names
1222                     that can be passed  to  the  project()  command.  Because
1223                     CMake only supports a single toolchain per language, this
1224                     field can be used as a key.
1225
1226              compiler
1227                     A JSON object containing members:
1228
1229                     path   Optional  member  that   is   present   when   the
1230                            CMAKE_<LANG>_COMPILER  variable is defined for the
1231                            current language. Its value is a JSON string hold‐
1232                            ing the path to the compiler.
1233
1234                     id     Optional   member   that   is   present  when  the
1235                            CMAKE_<LANG>_COMPILER_ID variable is  defined  for
1236                            the  current  language. Its value is a JSON string
1237                            holding the ID (GNU, MSVC, etc.) of the compiler.
1238
1239                     version
1240                            Optional  member  that   is   present   when   the
1241                            CMAKE_<LANG>_COMPILER_VERSION  variable is defined
1242                            for the current language.  Its  value  is  a  JSON
1243                            string holding the version of the compiler.
1244
1245                     target Optional   member   that   is   present  when  the
1246                            CMAKE_<LANG>_COMPILER_TARGET variable  is  defined
1247                            for  the  current  language.  Its  value is a JSON
1248                            string holding the cross-compiling target  of  the
1249                            compiler.
1250
1251                     implicit
1252                            A JSON object containing members:
1253
1254                            includeDirectories
1255                                   Optional  member  that  is present when the
1256                                   CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES
1257                                   variable  is  defined  for the current lan‐
1258                                   guage. Its value is a JSON  array  of  JSON
1259                                   strings  where  each string holds a path to
1260                                   an implicit include directory for the  com‐
1261                                   piler.
1262
1263                            linkDirectories
1264                                   Optional  member  that  is present when the
1265                                   CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES
1266                                   variable  is  defined  for the current lan‐
1267                                   guage. Its value is a JSON  array  of  JSON
1268                                   strings  where  each string holds a path to
1269                                   an implicit link  directory  for  the  com‐
1270                                   piler.
1271
1272                            linkFrameworkDirectories
1273                                   Optional  member  that  is present when the
1274                                   CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIREC‐
1275                                   TORIES  variable is defined for the current
1276                                   language. Its value is a JSON array of JSON
1277                                   strings  where  each string holds a path to
1278                                   an implicit link  framework  directory  for
1279                                   the compiler.
1280
1281                            linkLibraries
1282                                   Optional  member  that  is present when the
1283                                   CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES  vari‐
1284                                   able  is  defined for the current language.
1285                                   Its value is a JSON array of  JSON  strings
1286                                   where  each  string  holds a path to an im‐
1287                                   plicit link library for the compiler.
1288
1289              sourceFileExtensions
1290                     Optional   member    that    is    present    when    the
1291                     CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS  variable  is defined
1292                     for the current language. Its value is a  JSON  array  of
1293                     JSON  strings  where each each string holds a file exten‐
1294                     sion (without the leading dot) for the language.
1295
1297       2000-2021 Kitware, Inc. and Contributors
1298
1299
1300
1301
13023.20.3                           May 30, 2021                CMAKE-FILE-API(7)
Impressum