1320 lines
42 KiB
Groff
1320 lines
42 KiB
Groff
.\" Man page generated from reStructuredText.
|
||
.
|
||
.TH "CMAKE-FILE-API" "7" "Aug 20, 2020" "3.18.2" "CMake"
|
||
.SH NAME
|
||
cmake-file-api \- CMake File-Based API
|
||
.
|
||
.nr rst2man-indent-level 0
|
||
.
|
||
.de1 rstReportMargin
|
||
\\$1 \\n[an-margin]
|
||
level \\n[rst2man-indent-level]
|
||
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||
-
|
||
\\n[rst2man-indent0]
|
||
\\n[rst2man-indent1]
|
||
\\n[rst2man-indent2]
|
||
..
|
||
.de1 INDENT
|
||
.\" .rstReportMargin pre:
|
||
. RS \\$1
|
||
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
||
. nr rst2man-indent-level +1
|
||
.\" .rstReportMargin post:
|
||
..
|
||
.de UNINDENT
|
||
. RE
|
||
.\" indent \\n[an-margin]
|
||
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||
.nr rst2man-indent-level -1
|
||
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
||
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
||
..
|
||
.SH INTRODUCTION
|
||
.sp
|
||
CMake provides a file\-based API that clients may use to get semantic
|
||
information about the buildsystems CMake generates. Clients may use
|
||
the API by writing query files to a specific location in a build tree
|
||
to request zero or more \fI\%Object Kinds\fP\&. When CMake generates the
|
||
buildsystem in that build tree it will read the query files and write
|
||
reply files for the client to read.
|
||
.sp
|
||
The file\-based API uses a \fB<build>/.cmake/api/\fP directory at the top
|
||
of a build tree. The API is versioned to support changes to the layout
|
||
of files within the API directory. API file layout versioning is
|
||
orthogonal to the versioning of \fI\%Object Kinds\fP used in replies.
|
||
This version of CMake supports only one API version, \fI\%API v1\fP\&.
|
||
.SH API V1
|
||
.sp
|
||
API v1 is housed in the \fB<build>/.cmake/api/v1/\fP directory.
|
||
It has the following subdirectories:
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \fBquery/\fP
|
||
Holds query files written by clients.
|
||
These may be \fI\%v1 Shared Stateless Query Files\fP,
|
||
\fI\%v1 Client Stateless Query Files\fP, or \fI\%v1 Client Stateful Query Files\fP\&.
|
||
.TP
|
||
.B \fBreply/\fP
|
||
Holds reply files written by CMake whenever it runs to generate a build
|
||
system. These are indexed by a \fI\%v1 Reply Index File\fP file that may
|
||
reference additional \fI\%v1 Reply Files\fP\&. CMake owns all reply files.
|
||
Clients must never remove them.
|
||
.sp
|
||
Clients may look for and read a reply index file at any time.
|
||
Clients may optionally create the \fBreply/\fP directory at any time
|
||
and monitor it for the appearance of a new reply index file.
|
||
.UNINDENT
|
||
.SS v1 Shared Stateless Query Files
|
||
.sp
|
||
Shared stateless query files allow clients to share requests for
|
||
major versions of the \fI\%Object Kinds\fP and get all requested versions
|
||
recognized by the CMake that runs.
|
||
.sp
|
||
Clients may create shared requests by creating empty files in the
|
||
\fBv1/query/\fP directory. The form is:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
<build>/.cmake/api/v1/query/<kind>\-v<major>
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
where \fB<kind>\fP is one of the \fI\%Object Kinds\fP, \fB\-v\fP is literal,
|
||
and \fB<major>\fP is the major version number.
|
||
.sp
|
||
Files of this form are stateless shared queries not owned by any specific
|
||
client. Once created they should not be removed without external client
|
||
coordination or human intervention.
|
||
.SS v1 Client Stateless Query Files
|
||
.sp
|
||
Client stateless query files allow clients to create owned requests for
|
||
major versions of the \fI\%Object Kinds\fP and get all requested versions
|
||
recognized by the CMake that runs.
|
||
.sp
|
||
Clients may create owned requests by creating empty files in
|
||
client\-specific query subdirectories. The form is:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
<build>/.cmake/api/v1/query/client\-<client>/<kind>\-v<major>
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
where \fBclient\-\fP is literal, \fB<client>\fP is a string uniquely
|
||
identifying the client, \fB<kind>\fP is one of the \fI\%Object Kinds\fP,
|
||
\fB\-v\fP is literal, and \fB<major>\fP is the major version number.
|
||
Each client must choose a unique \fB<client>\fP identifier via its
|
||
own means.
|
||
.sp
|
||
Files of this form are stateless queries owned by the client \fB<client>\fP\&.
|
||
The owning client may remove them at any time.
|
||
.SS v1 Client Stateful Query Files
|
||
.sp
|
||
Stateful query files allow clients to request a list of versions of
|
||
each of the \fI\%Object Kinds\fP and get only the most recent version
|
||
recognized by the CMake that runs.
|
||
.sp
|
||
Clients may create owned stateful queries by creating \fBquery.json\fP
|
||
files in client\-specific query subdirectories. The form is:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
<build>/.cmake/api/v1/query/client\-<client>/query.json
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
where \fBclient\-\fP is literal, \fB<client>\fP is a string uniquely
|
||
identifying the client, and \fBquery.json\fP is literal. Each client
|
||
must choose a unique \fB<client>\fP identifier via its own means.
|
||
.sp
|
||
\fBquery.json\fP files are stateful queries owned by the client \fB<client>\fP\&.
|
||
The owning client may update or remove them at any time. When a
|
||
given client installation is updated it may then update the stateful
|
||
query it writes to build trees to request newer object versions.
|
||
This can be used to avoid asking CMake to generate multiple object
|
||
versions unnecessarily.
|
||
.sp
|
||
A \fBquery.json\fP file must contain a JSON object:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"requests": [
|
||
{ "kind": "<kind>" , "version": 1 },
|
||
{ "kind": "<kind>" , "version": { "major": 1, "minor": 2 } },
|
||
{ "kind": "<kind>" , "version": [2, 1] },
|
||
{ "kind": "<kind>" , "version": [2, { "major": 1, "minor": 2 }] },
|
||
{ "kind": "<kind>" , "version": 1, "client": {} },
|
||
{ "kind": "..." }
|
||
],
|
||
"client": {}
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
The members are:
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \fBrequests\fP
|
||
A JSON array containing zero or more requests. Each request is
|
||
a JSON object with members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBkind\fP
|
||
Specifies one of the \fI\%Object Kinds\fP to be included in the reply.
|
||
.TP
|
||
.B \fBversion\fP
|
||
Indicates the version(s) of the object kind that the client
|
||
understands. Versions have major and minor components following
|
||
semantic version conventions. The value must be
|
||
.INDENT 7.0
|
||
.IP \(bu 2
|
||
a JSON integer specifying a (non\-negative) major version number, or
|
||
.IP \(bu 2
|
||
a JSON object containing \fBmajor\fP and (optionally) \fBminor\fP
|
||
members specifying non\-negative integer version components, or
|
||
.IP \(bu 2
|
||
a JSON array whose elements are each one of the above.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBclient\fP
|
||
Optional member reserved for use by the client. This value is
|
||
preserved in the reply written for the client in the
|
||
\fI\%v1 Reply Index File\fP but is otherwise ignored. Clients may use
|
||
this to pass custom information with a request through to its reply.
|
||
.UNINDENT
|
||
.sp
|
||
For each requested object kind CMake will choose the \fIfirst\fP version
|
||
that it recognizes for that kind among those listed in the request.
|
||
The response will use the selected \fImajor\fP version with the highest
|
||
\fIminor\fP version known to the running CMake for that major version.
|
||
Therefore clients should list all supported major versions in
|
||
preferred order along with the minimal minor version required
|
||
for each major version.
|
||
.TP
|
||
.B \fBclient\fP
|
||
Optional member reserved for use by the client. This value is
|
||
preserved in the reply written for the client in the
|
||
\fI\%v1 Reply Index File\fP but is otherwise ignored. Clients may use
|
||
this to pass custom information with a query through to its reply.
|
||
.UNINDENT
|
||
.sp
|
||
Other \fBquery.json\fP top\-level members are reserved for future use.
|
||
If present they are ignored for forward compatibility.
|
||
.SS v1 Reply Index File
|
||
.sp
|
||
CMake writes an \fBindex\-*.json\fP file to the \fBv1/reply/\fP directory
|
||
whenever it runs to generate a build system. Clients must read the
|
||
reply index file first and may read other \fI\%v1 Reply Files\fP only by
|
||
following references. The form of the reply index file name is:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
<build>/.cmake/api/v1/reply/index\-<unspecified>.json
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
where \fBindex\-\fP is literal and \fB<unspecified>\fP is an unspecified
|
||
name selected by CMake. Whenever a new index file is generated it
|
||
is given a new name and any old one is deleted. During the short
|
||
time between these steps there may be multiple index files present;
|
||
the one with the largest name in lexicographic order is the current
|
||
index file.
|
||
.sp
|
||
The reply index file contains a JSON object:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"cmake": {
|
||
"version": {
|
||
"major": 3, "minor": 14, "patch": 0, "suffix": "",
|
||
"string": "3.14.0", "isDirty": false
|
||
},
|
||
"paths": {
|
||
"cmake": "/prefix/bin/cmake",
|
||
"ctest": "/prefix/bin/ctest",
|
||
"cpack": "/prefix/bin/cpack",
|
||
"root": "/prefix/share/cmake\-3.14"
|
||
},
|
||
"generator": {
|
||
"multiConfig": false,
|
||
"name": "Unix Makefiles"
|
||
}
|
||
},
|
||
"objects": [
|
||
{ "kind": "<kind>",
|
||
"version": { "major": 1, "minor": 0 },
|
||
"jsonFile": "<file>" },
|
||
{ "...": "..." }
|
||
],
|
||
"reply": {
|
||
"<kind>\-v<major>": { "kind": "<kind>",
|
||
"version": { "major": 1, "minor": 0 },
|
||
"jsonFile": "<file>" },
|
||
"<unknown>": { "error": "unknown query file" },
|
||
"...": {},
|
||
"client\-<client>": {
|
||
"<kind>\-v<major>": { "kind": "<kind>",
|
||
"version": { "major": 1, "minor": 0 },
|
||
"jsonFile": "<file>" },
|
||
"<unknown>": { "error": "unknown query file" },
|
||
"...": {},
|
||
"query.json": {
|
||
"requests": [ {}, {}, {} ],
|
||
"responses": [
|
||
{ "kind": "<kind>",
|
||
"version": { "major": 1, "minor": 0 },
|
||
"jsonFile": "<file>" },
|
||
{ "error": "unknown query file" },
|
||
{ "...": {} }
|
||
],
|
||
"client": {}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
The members are:
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \fBcmake\fP
|
||
A JSON object containing information about the instance of CMake that
|
||
generated the reply. It contains members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBversion\fP
|
||
A JSON object specifying the version of CMake with members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBmajor\fP, \fBminor\fP, \fBpatch\fP
|
||
Integer values specifying the major, minor, and patch version components.
|
||
.TP
|
||
.B \fBsuffix\fP
|
||
A string specifying the version suffix, if any, e.g. \fBg0abc3\fP\&.
|
||
.TP
|
||
.B \fBstring\fP
|
||
A string specifying the full version in the format
|
||
\fB<major>.<minor>.<patch>[\-<suffix>]\fP\&.
|
||
.TP
|
||
.B \fBisDirty\fP
|
||
A boolean indicating whether the version was built from a version
|
||
controlled source tree with local modifications.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBpaths\fP
|
||
A JSON object specifying paths to things that come with CMake.
|
||
It has members for \fBcmake\fP, \fBctest\fP, and \fBcpack\fP whose values
|
||
are JSON strings specifying the absolute path to each tool,
|
||
represented with forward slashes. It also has a \fBroot\fP member for
|
||
the absolute path to the directory containing CMake resources like the
|
||
\fBModules/\fP directory (see \fBCMAKE_ROOT\fP).
|
||
.TP
|
||
.B \fBgenerator\fP
|
||
A JSON object describing the CMake generator used for the build.
|
||
It has members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBmultiConfig\fP
|
||
A boolean specifying whether the generator supports multiple output
|
||
configurations.
|
||
.TP
|
||
.B \fBname\fP
|
||
A string specifying the name of the generator.
|
||
.TP
|
||
.B \fBplatform\fP
|
||
If the generator supports \fBCMAKE_GENERATOR_PLATFORM\fP,
|
||
this is a string specifying the generator platform name.
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBobjects\fP
|
||
A JSON array listing all versions of all \fI\%Object Kinds\fP generated
|
||
as part of the reply. Each array entry is a
|
||
\fI\%v1 Reply File Reference\fP\&.
|
||
.TP
|
||
.B \fBreply\fP
|
||
A JSON object mirroring the content of the \fBquery/\fP directory
|
||
that CMake loaded to produce the reply. The members are of the form
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fB<kind>\-v<major>\fP
|
||
A member of this form appears for each of the
|
||
\fI\%v1 Shared Stateless Query Files\fP that CMake recognized as a
|
||
request for object kind \fB<kind>\fP with major version \fB<major>\fP\&.
|
||
The value is a \fI\%v1 Reply File Reference\fP to the corresponding
|
||
reply file for that object kind and version.
|
||
.TP
|
||
.B \fB<unknown>\fP
|
||
A member of this form appears for each of the
|
||
\fI\%v1 Shared Stateless Query Files\fP that CMake did not recognize.
|
||
The value is a JSON object with a single \fBerror\fP member
|
||
containing a string with an error message indicating that the
|
||
query file is unknown.
|
||
.TP
|
||
.B \fBclient\-<client>\fP
|
||
A member of this form appears for each client\-owned directory
|
||
holding \fI\%v1 Client Stateless Query Files\fP\&.
|
||
The value is a JSON object mirroring the content of the
|
||
\fBquery/client\-<client>/\fP directory. The members are of the form:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fB<kind>\-v<major>\fP
|
||
A member of this form appears for each of the
|
||
\fI\%v1 Client Stateless Query Files\fP that CMake recognized as a
|
||
request for object kind \fB<kind>\fP with major version \fB<major>\fP\&.
|
||
The value is a \fI\%v1 Reply File Reference\fP to the corresponding
|
||
reply file for that object kind and version.
|
||
.TP
|
||
.B \fB<unknown>\fP
|
||
A member of this form appears for each of the
|
||
\fI\%v1 Client Stateless Query Files\fP that CMake did not recognize.
|
||
The value is a JSON object with a single \fBerror\fP member
|
||
containing a string with an error message indicating that the
|
||
query file is unknown.
|
||
.TP
|
||
.B \fBquery.json\fP
|
||
This member appears for clients using
|
||
\fI\%v1 Client Stateful Query Files\fP\&.
|
||
If the \fBquery.json\fP file failed to read or parse as a JSON object,
|
||
this member is a JSON object with a single \fBerror\fP member
|
||
containing a string with an error message. Otherwise, this member
|
||
is a JSON object mirroring the content of the \fBquery.json\fP file.
|
||
The members are:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBclient\fP
|
||
A copy of the \fBquery.json\fP file \fBclient\fP member, if it exists.
|
||
.TP
|
||
.B \fBrequests\fP
|
||
A copy of the \fBquery.json\fP file \fBrequests\fP member, if it exists.
|
||
.TP
|
||
.B \fBresponses\fP
|
||
If the \fBquery.json\fP file \fBrequests\fP member is missing or invalid,
|
||
this member is a JSON object with a single \fBerror\fP member
|
||
containing a string with an error message. Otherwise, this member
|
||
contains a JSON array with a response for each entry of the
|
||
\fBrequests\fP array, in the same order. Each response is
|
||
.INDENT 7.0
|
||
.IP \(bu 2
|
||
a JSON object with a single \fBerror\fP member containing a string
|
||
with an error message, or
|
||
.IP \(bu 2
|
||
a \fI\%v1 Reply File Reference\fP to the corresponding reply file for
|
||
the requested object kind and selected version.
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
After reading the reply index file, clients may read the other
|
||
\fI\%v1 Reply Files\fP it references.
|
||
.SS v1 Reply File Reference
|
||
.sp
|
||
The reply index file represents each reference to another reply file
|
||
using a JSON object with members:
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \fBkind\fP
|
||
A string specifying one of the \fI\%Object Kinds\fP\&.
|
||
.TP
|
||
.B \fBversion\fP
|
||
A JSON object with members \fBmajor\fP and \fBminor\fP specifying
|
||
integer version components of the object kind.
|
||
.TP
|
||
.B \fBjsonFile\fP
|
||
A JSON string specifying a path relative to the reply index file
|
||
to another JSON file containing the object.
|
||
.UNINDENT
|
||
.SS v1 Reply Files
|
||
.sp
|
||
Reply files containing specific \fI\%Object Kinds\fP are written by CMake.
|
||
The names of these files are unspecified and must not be interpreted
|
||
by clients. Clients must first read the \fI\%v1 Reply Index File\fP and
|
||
and follow references to the names of the desired response objects.
|
||
.sp
|
||
Reply files (including the index file) will never be replaced by
|
||
files of the same name but different content. This allows a client
|
||
to read the files concurrently with a running CMake that may generate
|
||
a new reply. However, after generating a new reply CMake will attempt
|
||
to remove reply files from previous runs that it did not just write.
|
||
If a client attempts to read a reply file referenced by the index but
|
||
finds the file missing, that means a concurrent CMake has generated
|
||
a new reply. The client may simply start again by reading the new
|
||
reply index file.
|
||
.SH OBJECT KINDS
|
||
.sp
|
||
The CMake file\-based API reports semantic information about the build
|
||
system using the following kinds of JSON objects. Each kind of object
|
||
is versioned independently using semantic versioning with major and
|
||
minor components. Every kind of object has the form:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"kind": "<kind>",
|
||
"version": { "major": 1, "minor": 0 },
|
||
"...": {}
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
The \fBkind\fP member is a string specifying the object kind name.
|
||
The \fBversion\fP member is a JSON object with \fBmajor\fP and \fBminor\fP
|
||
members specifying integer components of the object kind’s version.
|
||
Additional top\-level members are specific to each object kind.
|
||
.SS Object Kind “codemodel”
|
||
.sp
|
||
The \fBcodemodel\fP object kind describes the build system structure as
|
||
modeled by CMake.
|
||
.sp
|
||
There is only one \fBcodemodel\fP object major version, version 2.
|
||
Version 1 does not exist to avoid confusion with that from
|
||
\fBcmake\-server(7)\fP mode.
|
||
.SS “codemodel” version 2
|
||
.sp
|
||
\fBcodemodel\fP object version 2 is a JSON object:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"kind": "codemodel",
|
||
"version": { "major": 2, "minor": 1 },
|
||
"paths": {
|
||
"source": "/path/to/top\-level\-source\-dir",
|
||
"build": "/path/to/top\-level\-build\-dir"
|
||
},
|
||
"configurations": [
|
||
{
|
||
"name": "Debug",
|
||
"directories": [
|
||
{
|
||
"source": ".",
|
||
"build": ".",
|
||
"childIndexes": [ 1 ],
|
||
"projectIndex": 0,
|
||
"targetIndexes": [ 0 ],
|
||
"hasInstallRule": true,
|
||
"minimumCMakeVersion": {
|
||
"string": "3.14"
|
||
}
|
||
},
|
||
{
|
||
"source": "sub",
|
||
"build": "sub",
|
||
"parentIndex": 0,
|
||
"projectIndex": 0,
|
||
"targetIndexes": [ 1 ],
|
||
"minimumCMakeVersion": {
|
||
"string": "3.14"
|
||
}
|
||
}
|
||
],
|
||
"projects": [
|
||
{
|
||
"name": "MyProject",
|
||
"directoryIndexes": [ 0, 1 ],
|
||
"targetIndexes": [ 0, 1 ]
|
||
}
|
||
],
|
||
"targets": [
|
||
{
|
||
"name": "MyExecutable",
|
||
"directoryIndex": 0,
|
||
"projectIndex": 0,
|
||
"jsonFile": "<file>"
|
||
},
|
||
{
|
||
"name": "MyLibrary",
|
||
"directoryIndex": 1,
|
||
"projectIndex": 0,
|
||
"jsonFile": "<file>"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
The members specific to \fBcodemodel\fP objects are:
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \fBpaths\fP
|
||
A JSON object containing members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBsource\fP
|
||
A string specifying the absolute path to the top\-level source directory,
|
||
represented with forward slashes.
|
||
.TP
|
||
.B \fBbuild\fP
|
||
A string specifying the absolute path to the top\-level build directory,
|
||
represented with forward slashes.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBconfigurations\fP
|
||
A JSON array of entries corresponding to available build configurations.
|
||
On single\-configuration generators there is one entry for the value
|
||
of the \fBCMAKE_BUILD_TYPE\fP variable. For multi\-configuration
|
||
generators there is an entry for each configuration listed in the
|
||
\fBCMAKE_CONFIGURATION_TYPES\fP variable.
|
||
Each entry is a JSON object containing members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBname\fP
|
||
A string specifying the name of the configuration, e.g. \fBDebug\fP\&.
|
||
.TP
|
||
.B \fBdirectories\fP
|
||
A JSON array of entries each corresponding to a build system directory
|
||
whose source directory contains a \fBCMakeLists.txt\fP file. The first
|
||
entry corresponds to the top\-level directory. Each entry is a
|
||
JSON object containing members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBsource\fP
|
||
A string specifying the path to the source directory, represented
|
||
with forward slashes. If the directory is inside the top\-level
|
||
source directory then the path is specified relative to that
|
||
directory (with \fB\&.\fP for the top\-level source directory itself).
|
||
Otherwise the path is absolute.
|
||
.TP
|
||
.B \fBbuild\fP
|
||
A string specifying the path to the build directory, represented
|
||
with forward slashes. If the directory is inside the top\-level
|
||
build directory then the path is specified relative to that
|
||
directory (with \fB\&.\fP for the top\-level build directory itself).
|
||
Otherwise the path is absolute.
|
||
.TP
|
||
.B \fBparentIndex\fP
|
||
Optional member that is present when the directory is not top\-level.
|
||
The value is an unsigned integer 0\-based index of another entry in
|
||
the main \fBdirectories\fP array that corresponds to the parent
|
||
directory that added this directory as a subdirectory.
|
||
.TP
|
||
.B \fBchildIndexes\fP
|
||
Optional member that is present when the directory has subdirectories.
|
||
The value is a JSON array of entries corresponding to child directories
|
||
created by the \fBadd_subdirectory()\fP or \fBsubdirs()\fP
|
||
command. Each entry is an unsigned integer 0\-based index of another
|
||
entry in the main \fBdirectories\fP array.
|
||
.TP
|
||
.B \fBprojectIndex\fP
|
||
An unsigned integer 0\-based index into the main \fBprojects\fP array
|
||
indicating the build system project to which the this directory belongs.
|
||
.TP
|
||
.B \fBtargetIndexes\fP
|
||
Optional member that is present when the directory itself has targets,
|
||
excluding those belonging to subdirectories. The value is a JSON
|
||
array of entries corresponding to the targets. Each entry is an
|
||
unsigned integer 0\-based index into the main \fBtargets\fP array.
|
||
.TP
|
||
.B \fBminimumCMakeVersion\fP
|
||
Optional member present when a minimum required version of CMake is
|
||
known for the directory. This is the \fB<min>\fP version given to the
|
||
most local call to the \fBcmake_minimum_required(VERSION)\fP
|
||
command in the directory itself or one of its ancestors.
|
||
The value is a JSON object with one member:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBstring\fP
|
||
A string specifying the minimum required version in the format:
|
||
.INDENT 7.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
<major>.<minor>[.<patch>[.<tweak>]][<suffix>]
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
Each component is an unsigned integer and the suffix may be an
|
||
arbitrary string.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBhasInstallRule\fP
|
||
Optional member that is present with boolean value \fBtrue\fP when
|
||
the directory or one of its subdirectories contains any
|
||
\fBinstall()\fP rules, i.e. whether a \fBmake install\fP
|
||
or equivalent rule is available.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBprojects\fP
|
||
A JSON array of entries corresponding to the top\-level project
|
||
and sub\-projects defined in the build system. Each (sub\-)project
|
||
corresponds to a source directory whose \fBCMakeLists.txt\fP file
|
||
calls the \fBproject()\fP command with a project name different
|
||
from its parent directory. The first entry corresponds to the
|
||
top\-level project.
|
||
.sp
|
||
Each entry is a JSON object containing members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBname\fP
|
||
A string specifying the name given to the \fBproject()\fP command.
|
||
.TP
|
||
.B \fBparentIndex\fP
|
||
Optional member that is present when the project is not top\-level.
|
||
The value is an unsigned integer 0\-based index of another entry in
|
||
the main \fBprojects\fP array that corresponds to the parent project
|
||
that added this project as a sub\-project.
|
||
.TP
|
||
.B \fBchildIndexes\fP
|
||
Optional member that is present when the project has sub\-projects.
|
||
The value is a JSON array of entries corresponding to the sub\-projects.
|
||
Each entry is an unsigned integer 0\-based index of another
|
||
entry in the main \fBprojects\fP array.
|
||
.TP
|
||
.B \fBdirectoryIndexes\fP
|
||
A JSON array of entries corresponding to build system directories
|
||
that are part of the project. The first entry corresponds to the
|
||
top\-level directory of the project. Each entry is an unsigned
|
||
integer 0\-based index into the main \fBdirectories\fP array.
|
||
.TP
|
||
.B \fBtargetIndexes\fP
|
||
Optional member that is present when the project itself has targets,
|
||
excluding those belonging to sub\-projects. The value is a JSON
|
||
array of entries corresponding to the targets. Each entry is an
|
||
unsigned integer 0\-based index into the main \fBtargets\fP array.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBtargets\fP
|
||
A JSON array of entries corresponding to the build system targets.
|
||
Such targets are created by calls to \fBadd_executable()\fP,
|
||
\fBadd_library()\fP, and \fBadd_custom_target()\fP, excluding
|
||
imported targets and interface libraries (which do not generate any
|
||
build rules). Each entry is a JSON object containing members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBname\fP
|
||
A string specifying the target name.
|
||
.TP
|
||
.B \fBid\fP
|
||
A string uniquely identifying the target. This matches the \fBid\fP
|
||
field in the file referenced by \fBjsonFile\fP\&.
|
||
.TP
|
||
.B \fBdirectoryIndex\fP
|
||
An unsigned integer 0\-based index into the main \fBdirectories\fP array
|
||
indicating the build system directory in which the target is defined.
|
||
.TP
|
||
.B \fBprojectIndex\fP
|
||
An unsigned integer 0\-based index into the main \fBprojects\fP array
|
||
indicating the build system project in which the target is defined.
|
||
.TP
|
||
.B \fBjsonFile\fP
|
||
A JSON string specifying a path relative to the codemodel file
|
||
to another JSON file containing a
|
||
\fI\%“codemodel” version 2 “target” object\fP\&.
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS “codemodel” version 2 “target” object
|
||
.sp
|
||
A codemodel “target” object is referenced by a \fI\%“codemodel” version 2\fP
|
||
object’s \fBtargets\fP array. Each “target” object is a JSON object
|
||
with members:
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \fBname\fP
|
||
A string specifying the logical name of the target.
|
||
.TP
|
||
.B \fBid\fP
|
||
A string uniquely identifying the target. The format is unspecified
|
||
and should not be interpreted by clients.
|
||
.TP
|
||
.B \fBtype\fP
|
||
A string specifying the type of the target. The value is one of
|
||
\fBEXECUTABLE\fP, \fBSTATIC_LIBRARY\fP, \fBSHARED_LIBRARY\fP,
|
||
\fBMODULE_LIBRARY\fP, \fBOBJECT_LIBRARY\fP, or \fBUTILITY\fP\&.
|
||
.TP
|
||
.B \fBbacktrace\fP
|
||
Optional member that is present when a CMake language backtrace to
|
||
the command in the source code that created the target is available.
|
||
The value is an unsigned integer 0\-based index into the
|
||
\fBbacktraceGraph\fP member’s \fBnodes\fP array.
|
||
.TP
|
||
.B \fBfolder\fP
|
||
Optional member that is present when the \fBFOLDER\fP target
|
||
property is set. The value is a JSON object with one member:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBname\fP
|
||
A string specifying the name of the target folder.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBpaths\fP
|
||
A JSON object containing members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBsource\fP
|
||
A string specifying the path to the target’s source directory,
|
||
represented with forward slashes. If the directory is inside the
|
||
top\-level source directory then the path is specified relative to
|
||
that directory (with \fB\&.\fP for the top\-level source directory itself).
|
||
Otherwise the path is absolute.
|
||
.TP
|
||
.B \fBbuild\fP
|
||
A string specifying the path to the target’s build directory,
|
||
represented with forward slashes. If the directory is inside the
|
||
top\-level build directory then the path is specified relative to
|
||
that directory (with \fB\&.\fP for the top\-level build directory itself).
|
||
Otherwise the path is absolute.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBnameOnDisk\fP
|
||
Optional member that is present for executable and library targets
|
||
that are linked or archived into a single primary artifact.
|
||
The value is a string specifying the file name of that artifact on disk.
|
||
.TP
|
||
.B \fBartifacts\fP
|
||
Optional member that is present for executable and library targets
|
||
that produce artifacts on disk meant for consumption by dependents.
|
||
The value is a JSON array of entries corresponding to the artifacts.
|
||
Each entry is a JSON object containing one member:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBpath\fP
|
||
A string specifying the path to the file on disk, represented with
|
||
forward slashes. If the file is inside the top\-level build directory
|
||
then the path is specified relative to that directory.
|
||
Otherwise the path is absolute.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBisGeneratorProvided\fP
|
||
Optional member that is present with boolean value \fBtrue\fP if the
|
||
target is provided by CMake’s build system generator rather than by
|
||
a command in the source code.
|
||
.TP
|
||
.B \fBinstall\fP
|
||
Optional member that is present when the target has an \fBinstall()\fP
|
||
rule. The value is a JSON object with members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBprefix\fP
|
||
A JSON object specifying the installation prefix. It has one member:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBpath\fP
|
||
A string specifying the value of \fBCMAKE_INSTALL_PREFIX\fP\&.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBdestinations\fP
|
||
A JSON array of entries specifying an install destination path.
|
||
Each entry is a JSON object with members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBpath\fP
|
||
A string specifying the install destination path. The path may
|
||
be absolute or relative to the install prefix.
|
||
.TP
|
||
.B \fBbacktrace\fP
|
||
Optional member that is present when a CMake language backtrace to
|
||
the \fBinstall()\fP command invocation that specified this
|
||
destination is available. The value is an unsigned integer 0\-based
|
||
index into the \fBbacktraceGraph\fP member’s \fBnodes\fP array.
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBlink\fP
|
||
Optional member that is present for executables and shared library
|
||
targets that link into a runtime binary. The value is a JSON object
|
||
with members describing the link step:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBlanguage\fP
|
||
A string specifying the language (e.g. \fBC\fP, \fBCXX\fP, \fBFortran\fP)
|
||
of the toolchain is used to invoke the linker.
|
||
.TP
|
||
.B \fBcommandFragments\fP
|
||
Optional member that is present when fragments of the link command
|
||
line invocation are available. The value is a JSON array of entries
|
||
specifying ordered fragments. Each entry is a JSON object with members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBfragment\fP
|
||
A string specifying a fragment of the link command line invocation.
|
||
The value is encoded in the build system’s native shell format.
|
||
.TP
|
||
.B \fBrole\fP
|
||
A string specifying the role of the fragment’s content:
|
||
.INDENT 7.0
|
||
.IP \(bu 2
|
||
\fBflags\fP: link flags.
|
||
.IP \(bu 2
|
||
\fBlibraries\fP: link library file paths or flags.
|
||
.IP \(bu 2
|
||
\fBlibraryPath\fP: library search path flags.
|
||
.IP \(bu 2
|
||
\fBframeworkPath\fP: macOS framework search path flags.
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBlto\fP
|
||
Optional member that is present with boolean value \fBtrue\fP
|
||
when link\-time optimization (a.k.a. interprocedural optimization
|
||
or link\-time code generation) is enabled.
|
||
.TP
|
||
.B \fBsysroot\fP
|
||
Optional member that is present when the \fBCMAKE_SYSROOT_LINK\fP
|
||
or \fBCMAKE_SYSROOT\fP variable is defined. The value is a
|
||
JSON object with one member:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBpath\fP
|
||
A string specifying the absolute path to the sysroot, represented
|
||
with forward slashes.
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBarchive\fP
|
||
Optional member that is present for static library targets. The value
|
||
is a JSON object with members describing the archive step:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBcommandFragments\fP
|
||
Optional member that is present when fragments of the archiver command
|
||
line invocation are available. The value is a JSON array of entries
|
||
specifying the fragments. Each entry is a JSON object with members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBfragment\fP
|
||
A string specifying a fragment of the archiver command line invocation.
|
||
The value is encoded in the build system’s native shell format.
|
||
.TP
|
||
.B \fBrole\fP
|
||
A string specifying the role of the fragment’s content:
|
||
.INDENT 7.0
|
||
.IP \(bu 2
|
||
\fBflags\fP: archiver flags.
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBlto\fP
|
||
Optional member that is present with boolean value \fBtrue\fP
|
||
when link\-time optimization (a.k.a. interprocedural optimization
|
||
or link\-time code generation) is enabled.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBdependencies\fP
|
||
Optional member that is present when the target depends on other targets.
|
||
The value is a JSON array of entries corresponding to the dependencies.
|
||
Each entry is a JSON object with members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBid\fP
|
||
A string uniquely identifying the target on which this target depends.
|
||
This matches the main \fBid\fP member of the other target.
|
||
.TP
|
||
.B \fBbacktrace\fP
|
||
Optional member that is present when a CMake language backtrace to
|
||
the \fBadd_dependencies()\fP, \fBtarget_link_libraries()\fP,
|
||
or other command invocation that created this dependency is
|
||
available. The value is an unsigned integer 0\-based index into
|
||
the \fBbacktraceGraph\fP member’s \fBnodes\fP array.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBsources\fP
|
||
A JSON array of entries corresponding to the target’s source files.
|
||
Each entry is a JSON object with members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBpath\fP
|
||
A string specifying the path to the source file on disk, represented
|
||
with forward slashes. If the file is inside the top\-level source
|
||
directory then the path is specified relative to that directory.
|
||
Otherwise the path is absolute.
|
||
.TP
|
||
.B \fBcompileGroupIndex\fP
|
||
Optional member that is present when the source is compiled.
|
||
The value is an unsigned integer 0\-based index into the
|
||
\fBcompileGroups\fP array.
|
||
.TP
|
||
.B \fBsourceGroupIndex\fP
|
||
Optional member that is present when the source is part of a source
|
||
group either via the \fBsource_group()\fP command or by default.
|
||
The value is an unsigned integer 0\-based index into the
|
||
\fBsourceGroups\fP array.
|
||
.TP
|
||
.B \fBisGenerated\fP
|
||
Optional member that is present with boolean value \fBtrue\fP if
|
||
the source is \fBGENERATED\fP\&.
|
||
.TP
|
||
.B \fBbacktrace\fP
|
||
Optional member that is present when a CMake language backtrace to
|
||
the \fBtarget_sources()\fP, \fBadd_executable()\fP,
|
||
\fBadd_library()\fP, \fBadd_custom_target()\fP, or other
|
||
command invocation that added this source to the target is
|
||
available. The value is an unsigned integer 0\-based index into
|
||
the \fBbacktraceGraph\fP member’s \fBnodes\fP array.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBsourceGroups\fP
|
||
Optional member that is present when sources are grouped together by
|
||
the \fBsource_group()\fP command or by default. The value is a
|
||
JSON array of entries corresponding to the groups. Each entry is
|
||
a JSON object with members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBname\fP
|
||
A string specifying the name of the source group.
|
||
.TP
|
||
.B \fBsourceIndexes\fP
|
||
A JSON array listing the sources belonging to the group.
|
||
Each entry is an unsigned integer 0\-based index into the
|
||
main \fBsources\fP array for the target.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBcompileGroups\fP
|
||
Optional member that is present when the target has sources that compile.
|
||
The value is a JSON array of entries corresponding to groups of sources
|
||
that all compile with the same settings. Each entry is a JSON object
|
||
with members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBsourceIndexes\fP
|
||
A JSON array listing the sources belonging to the group.
|
||
Each entry is an unsigned integer 0\-based index into the
|
||
main \fBsources\fP array for the target.
|
||
.TP
|
||
.B \fBlanguage\fP
|
||
A string specifying the language (e.g. \fBC\fP, \fBCXX\fP, \fBFortran\fP)
|
||
of the toolchain is used to compile the source file.
|
||
.TP
|
||
.B \fBcompileCommandFragments\fP
|
||
Optional member that is present when fragments of the compiler command
|
||
line invocation are available. The value is a JSON array of entries
|
||
specifying ordered fragments. Each entry is a JSON object with
|
||
one member:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBfragment\fP
|
||
A string specifying a fragment of the compile command line invocation.
|
||
The value is encoded in the build system’s native shell format.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBincludes\fP
|
||
Optional member that is present when there are include directories.
|
||
The value is a JSON array with an entry for each directory. Each
|
||
entry is a JSON object with members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBpath\fP
|
||
A string specifying the path to the include directory,
|
||
represented with forward slashes.
|
||
.TP
|
||
.B \fBisSystem\fP
|
||
Optional member that is present with boolean value \fBtrue\fP if
|
||
the include directory is marked as a system include directory.
|
||
.TP
|
||
.B \fBbacktrace\fP
|
||
Optional member that is present when a CMake language backtrace to
|
||
the \fBtarget_include_directories()\fP or other command invocation
|
||
that added this include directory is available. The value is
|
||
an unsigned integer 0\-based index into the \fBbacktraceGraph\fP
|
||
member’s \fBnodes\fP array.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBprecompileHeaders\fP
|
||
Optional member that is present when \fBtarget_precompile_headers()\fP
|
||
or other command invocations set \fBPRECOMPILE_HEADERS\fP on the
|
||
target. The value is a JSON array with an entry for each header. Each
|
||
entry is a JSON object with members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBheader\fP
|
||
Full path to the precompile header file.
|
||
.TP
|
||
.B \fBbacktrace\fP
|
||
Optional member that is present when a CMake language backtrace to
|
||
the \fBtarget_precompile_headers()\fP or other command invocation
|
||
that added this precompiled header is available. The value is an
|
||
unsigned integer 0\-based index into the \fBbacktraceGraph\fP member’s
|
||
\fBnodes\fP array.
|
||
.UNINDENT
|
||
.sp
|
||
This field was added in codemodel version 2.1.
|
||
.TP
|
||
.B \fBdefines\fP
|
||
Optional member that is present when there are preprocessor definitions.
|
||
The value is a JSON array with an entry for each definition. Each
|
||
entry is a JSON object with members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBdefine\fP
|
||
A string specifying the preprocessor definition in the format
|
||
\fB<name>[=<value>]\fP, e.g. \fBDEF\fP or \fBDEF=1\fP\&.
|
||
.TP
|
||
.B \fBbacktrace\fP
|
||
Optional member that is present when a CMake language backtrace to
|
||
the \fBtarget_compile_definitions()\fP or other command invocation
|
||
that added this preprocessor definition is available. The value is
|
||
an unsigned integer 0\-based index into the \fBbacktraceGraph\fP
|
||
member’s \fBnodes\fP array.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBsysroot\fP
|
||
Optional member that is present when the
|
||
\fBCMAKE_SYSROOT_COMPILE\fP or \fBCMAKE_SYSROOT\fP
|
||
variable is defined. The value is a JSON object with one member:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBpath\fP
|
||
A string specifying the absolute path to the sysroot, represented
|
||
with forward slashes.
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBbacktraceGraph\fP
|
||
A JSON object describing the graph of backtraces whose nodes are
|
||
referenced from \fBbacktrace\fP members elsewhere. The members are:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBnodes\fP
|
||
A JSON array listing nodes in the backtrace graph. Each entry
|
||
is a JSON object with members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBfile\fP
|
||
An unsigned integer 0\-based index into the backtrace \fBfiles\fP array.
|
||
.TP
|
||
.B \fBline\fP
|
||
An optional member present when the node represents a line within
|
||
the file. The value is an unsigned integer 1\-based line number.
|
||
.TP
|
||
.B \fBcommand\fP
|
||
An optional member present when the node represents a command
|
||
invocation within the file. The value is an unsigned integer
|
||
0\-based index into the backtrace \fBcommands\fP array.
|
||
.TP
|
||
.B \fBparent\fP
|
||
An optional member present when the node is not the bottom of
|
||
the call stack. The value is an unsigned integer 0\-based index
|
||
of another entry in the backtrace \fBnodes\fP array.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBcommands\fP
|
||
A JSON array listing command names referenced by backtrace nodes.
|
||
Each entry is a string specifying a command name.
|
||
.TP
|
||
.B \fBfiles\fP
|
||
A JSON array listing CMake language files referenced by backtrace nodes.
|
||
Each entry is a string specifying the path to a file, represented
|
||
with forward slashes. If the file is inside the top\-level source
|
||
directory then the path is specified relative to that directory.
|
||
Otherwise the path is absolute.
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS Object Kind “cache”
|
||
.sp
|
||
The \fBcache\fP object kind lists cache entries. These are the
|
||
CMake Language Variables stored in the persistent cache
|
||
(\fBCMakeCache.txt\fP) for the build tree.
|
||
.sp
|
||
There is only one \fBcache\fP object major version, version 2.
|
||
Version 1 does not exist to avoid confusion with that from
|
||
\fBcmake\-server(7)\fP mode.
|
||
.SS “cache” version 2
|
||
.sp
|
||
\fBcache\fP object version 2 is a JSON object:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"kind": "cache",
|
||
"version": { "major": 2, "minor": 0 },
|
||
"entries": [
|
||
{
|
||
"name": "BUILD_SHARED_LIBS",
|
||
"value": "ON",
|
||
"type": "BOOL",
|
||
"properties": [
|
||
{
|
||
"name": "HELPSTRING",
|
||
"value": "Build shared libraries"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"name": "CMAKE_GENERATOR",
|
||
"value": "Unix Makefiles",
|
||
"type": "INTERNAL",
|
||
"properties": [
|
||
{
|
||
"name": "HELPSTRING",
|
||
"value": "Name of generator."
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
The members specific to \fBcache\fP objects are:
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \fBentries\fP
|
||
A JSON array whose entries are each a JSON object specifying a
|
||
cache entry. The members of each entry are:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBname\fP
|
||
A string specifying the name of the entry.
|
||
.TP
|
||
.B \fBvalue\fP
|
||
A string specifying the value of the entry.
|
||
.TP
|
||
.B \fBtype\fP
|
||
A string specifying the type of the entry used by
|
||
\fBcmake\-gui(1)\fP to choose a widget for editing.
|
||
.TP
|
||
.B \fBproperties\fP
|
||
A JSON array of entries specifying associated
|
||
cache entry properties\&.
|
||
Each entry is a JSON object containing members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBname\fP
|
||
A string specifying the name of the cache entry property.
|
||
.TP
|
||
.B \fBvalue\fP
|
||
A string specifying the value of the cache entry property.
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS Object Kind “cmakeFiles”
|
||
.sp
|
||
The \fBcmakeFiles\fP object kind lists files used by CMake while
|
||
configuring and generating the build system. These include the
|
||
\fBCMakeLists.txt\fP files as well as included \fB\&.cmake\fP files.
|
||
.sp
|
||
There is only one \fBcmakeFiles\fP object major version, version 1.
|
||
.SS “cmakeFiles” version 1
|
||
.sp
|
||
\fBcmakeFiles\fP object version 1 is a JSON object:
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
{
|
||
"kind": "cmakeFiles",
|
||
"version": { "major": 1, "minor": 0 },
|
||
"paths": {
|
||
"build": "/path/to/top\-level\-build\-dir",
|
||
"source": "/path/to/top\-level\-source\-dir"
|
||
},
|
||
"inputs": [
|
||
{
|
||
"path": "CMakeLists.txt"
|
||
},
|
||
{
|
||
"isGenerated": true,
|
||
"path": "/path/to/top\-level\-build\-dir/.../CMakeSystem.cmake"
|
||
},
|
||
{
|
||
"isExternal": true,
|
||
"path": "/path/to/external/third\-party/module.cmake"
|
||
},
|
||
{
|
||
"isCMake": true,
|
||
"isExternal": true,
|
||
"path": "/path/to/cmake/Modules/CMakeGenericSystem.cmake"
|
||
}
|
||
]
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.sp
|
||
The members specific to \fBcmakeFiles\fP objects are:
|
||
.INDENT 0.0
|
||
.TP
|
||
.B \fBpaths\fP
|
||
A JSON object containing members:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBsource\fP
|
||
A string specifying the absolute path to the top\-level source directory,
|
||
represented with forward slashes.
|
||
.TP
|
||
.B \fBbuild\fP
|
||
A string specifying the absolute path to the top\-level build directory,
|
||
represented with forward slashes.
|
||
.UNINDENT
|
||
.TP
|
||
.B \fBinputs\fP
|
||
A JSON array whose entries are each a JSON object specifying an input
|
||
file used by CMake when configuring and generating the build system.
|
||
The members of each entry are:
|
||
.INDENT 7.0
|
||
.TP
|
||
.B \fBpath\fP
|
||
A string specifying the path to an input file to CMake, represented
|
||
with forward slashes. If the file is inside the top\-level source
|
||
directory then the path is specified relative to that directory.
|
||
Otherwise the path is absolute.
|
||
.TP
|
||
.B \fBisGenerated\fP
|
||
Optional member that is present with boolean value \fBtrue\fP
|
||
if the path specifies a file that is under the top\-level
|
||
build directory and the build is out\-of\-source.
|
||
This member is not available on in\-source builds.
|
||
.TP
|
||
.B \fBisExternal\fP
|
||
Optional member that is present with boolean value \fBtrue\fP
|
||
if the path specifies a file that is not under the top\-level
|
||
source or build directories.
|
||
.TP
|
||
.B \fBisCMake\fP
|
||
Optional member that is present with boolean value \fBtrue\fP
|
||
if the path specifies a file in the CMake installation.
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SH COPYRIGHT
|
||
2000-2020 Kitware, Inc. and Contributors
|
||
.\" Generated by docutils manpage writer.
|
||
.
|