CMAKE-FILE-API(7) CMake CMAKE-FILE-API(7)
NAME
cmake-file-api - CMake File-Based API
INTRODUCTION
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 Object Kinds. When CMake generates the
buildsystem in that build tree it will read the query files and write
reply files for the client to read.
The file-based API uses a <build>/.cmake/api/ 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 orthogo-
nal to the versioning of Object Kinds used in replies. This version of
CMake supports only one API version, API v1.
API V1
API v1 is housed in the <build>/.cmake/api/v1/ directory. It has the
following subdirectories:
query/ Holds query files written by clients. These may be v1 Shared
Stateless Query Files, v1 Client Stateless Query Files, or v1
Client Stateful Query Files.
reply/ Holds reply files written by CMake whenever it runs to generate
a build system. These are indexed by a v1 Reply Index File file
that may reference additional v1 Reply Files. CMake owns all
reply files. Clients must never remove them.
Clients may look for and read a reply index file at any time.
Clients may optionally create the reply/ directory at any time
and monitor it for the appearance of a new reply index file.
v1 Shared Stateless Query Files
Shared stateless query files allow clients to share requests for major
versions of the Object Kinds and get all requested versions recognized
by the CMake that runs.
Clients may create shared requests by creating empty files in the
v1/query/ directory. The form is:
<build>/.cmake/api/v1/query/<kind>-v<major>
where <kind> is one of the Object Kinds, -v is literal, and <major> is
the major version number.
Files of this form are stateless shared queries not owned by any spe-
cific client. Once created they should not be removed without external
client coordination or human intervention.
v1 Client Stateless Query Files
Client stateless query files allow clients to create owned requests for
major versions of the Object Kinds and get all requested versions rec-
ognized by the CMake that runs.
Clients may create owned requests by creating empty files in
client-specific query subdirectories. The form is:
<build>/.cmake/api/v1/query/client-<client>/<kind>-v<major>
where client- is literal, <client> is a string uniquely identifying the
client, <kind> is one of the Object Kinds, -v is literal, and <major>
is the major version number. Each client must choose a unique <client>
identifier via its own means.
Files of this form are stateless queries owned by the client <client>.
The owning client may remove them at any time.
v1 Client Stateful Query Files
Stateful query files allow clients to request a list of versions of
each of the Object Kinds and get only the most recent version recog-
nized by the CMake that runs.
Clients may create owned stateful queries by creating query.json files
in client-specific query subdirectories. The form is:
<build>/.cmake/api/v1/query/client-<client>/query.json
where client- is literal, <client> is a string uniquely identifying the
client, and query.json is literal. Each client must choose a unique
<client> identifier via its own means.
query.json files are stateful queries owned by the client <client>.
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 unnec-
essarily.
A query.json file must contain a JSON object:
{
"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": {}
}
The members are:
requests
A JSON array containing zero or more requests. Each request is
a JSON object with members:
kind Specifies one of the Object Kinds to be included in the
reply.
version
Indicates the version(s) of the object kind that the
client understands. Versions have major and minor compo-
nents following semantic version conventions. The value
must be
o a JSON integer specifying a (non-negative) major ver-
sion number, or
o a JSON object containing major and (optionally) minor
members specifying non-negative integer version compo-
nents, or
o a JSON array whose elements are each one of the above.
client Optional member reserved for use by the client. This
value is preserved in the reply written for the client in
the v1 Reply Index File but is otherwise ignored.
Clients may use this to pass custom information with a
request through to its reply.
For each requested object kind CMake will choose the first ver-
sion that it recognizes for that kind among those listed in the
request. The response will use the selected major version with
the highest minor version known to the running CMake for that
major version. Therefore clients should list all supported ma-
jor versions in preferred order along with the minimal minor
version required for each major version.
client Optional member reserved for use by the client. This value is
preserved in the reply written for the client in the v1 Reply
Index File but is otherwise ignored. Clients may use this to
pass custom information with a query through to its reply.
Other query.json top-level members are reserved for future use. If
present they are ignored for forward compatibility.
v1 Reply Index File
CMake writes an index-*.json file to the v1/reply/ directory whenever
it runs to generate a build system. Clients must read the reply index
file first and may read other v1 Reply Files only by following refer-
ences. The form of the reply index file name is:
<build>/.cmake/api/v1/reply/index-<unspecified>.json
where index- is literal and <unspecified> is an unspecified name se-
lected 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.
The reply index file contains a JSON object:
{
"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": {}
}
}
}
}
The members are:
cmake A JSON object containing information about the instance of CMake
that generated the reply. It contains members:
version
A JSON object specifying the version of CMake with mem-
bers:
major, minor, patch
Integer values specifying the major, minor, and
patch version components.
suffix A string specifying the version suffix, if any,
e.g. g0abc3.
string A string specifying the full version in the format
<major>.<minor>.<patch>[-<suffix>].
isDirty
A boolean indicating whether the version was built
from a version controlled source tree with local
modifications.
paths A JSON object specifying paths to things that come with
CMake. It has members for cmake, ctest, and cpack whose
values are JSON strings specifying the absolute path to
each tool, represented with forward slashes. It also has
a root member for the absolute path to the directory con-
taining CMake resources like the Modules/ directory (see
CMAKE_ROOT).
generator
A JSON object describing the CMake generator used for the
build. It has members:
multiConfig
A boolean specifying whether the generator sup-
ports multiple output configurations.
name A string specifying the name of the generator.
platform
If the generator supports CMAKE_GENERATOR_PLAT-
FORM, this is a string specifying the generator
platform name.
objects
A JSON array listing all versions of all Object Kinds generated
as part of the reply. Each array entry is a v1 Reply File Ref-
erence.
reply A JSON object mirroring the content of the query/ directory that
CMake loaded to produce the reply. The members are of the form
<kind>-v<major>
A member of this form appears for each of the v1 Shared
Stateless Query Files that CMake recognized as a request
for object kind <kind> with major version <major>. The
value is a v1 Reply File Reference to the corresponding
reply file for that object kind and version.
<unknown>
A member of this form appears for each of the v1 Shared
Stateless Query Files that CMake did not recognize. The
value is a JSON object with a single error member con-
taining a string with an error message indicating that
the query file is unknown.
client-<client>
A member of this form appears for each client-owned di-
rectory holding v1 Client Stateless Query Files. The
value is a JSON object mirroring the content of the
query/client-<client>/ directory. The members are of the
form:
<kind>-v<major>
A member of this form appears for each of the v1
Client Stateless Query Files that CMake recognized
as a request for object kind <kind> with major
version <major>. The value is a v1 Reply File
Reference to the corresponding reply file for that
object kind and version.
<unknown>
A member of this form appears for each of the v1
Client Stateless Query Files that CMake did not
recognize. The value is a JSON object with a sin-
gle error member containing a string with an error
message indicating that the query file is unknown.
query.json
This member appears for clients using v1 Client
Stateful Query Files. If the query.json file
failed to read or parse as a JSON object, this
member is a JSON object with a single error member
containing a string with an error message. Other-
wise, this member is a JSON object mirroring the
content of the query.json file. The members are:
client A copy of the query.json file client mem-
ber, if it exists.
requests
A copy of the query.json file requests mem-
ber, if it exists.
responses
If the query.json file requests member is
missing or invalid, this member is a JSON
object with a single error member contain-
ing a string with an error message. Other-
wise, this member contains a JSON array
with a response for each entry of the re-
quests array, in the same order. Each re-
sponse is
o a JSON object with a single error member
containing a string with an error mes-
sage, or
o a v1 Reply File Reference to the corre-
sponding reply file for the requested ob-
ject kind and selected version.
After reading the reply index file, clients may read the other v1 Reply
Files it references.
v1 Reply File Reference
The reply index file represents each reference to another reply file
using a JSON object with members:
kind A string specifying one of the Object Kinds.
version
A JSON object with members major and minor specifying integer
version components of the object kind.
jsonFile
A JSON string specifying a path relative to the reply index file
to another JSON file containing the object.
v1 Reply Files
Reply files containing specific Object Kinds are written by CMake. The
names of these files are unspecified and must not be interpreted by
clients. Clients must first read the v1 Reply Index File and and fol-
low references to the names of the desired response objects.
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 re-
ply. However, after generating a new reply CMake will attempt to re-
move 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 re-
ply. The client may simply start again by reading the new reply index
file.
OBJECT KINDS
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 mi-
nor components. Every kind of object has the form:
{
"kind": "<kind>",
"version": { "major": 1, "minor": 0 },
"...": {}
}
The kind member is a string specifying the object kind name. The ver-
sion member is a JSON object with major and minor members specifying
integer components of the object kinds version. Additional top-level
members are specific to each object kind.
Object Kind codemodel
The codemodel object kind describes the build system structure as mod-
eled by CMake.
There is only one codemodel object major version, version 2. Version 1
does not exist to avoid confusion with that from cmake-server(7) mode.
codemodel version 2
codemodel object version 2 is a JSON object:
{
"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>"
}
]
}
]
}
The members specific to codemodel objects are:
paths A JSON object containing members:
source A string specifying the absolute path to the top-level
source directory, represented with forward slashes.
build A string specifying the absolute path to the top-level
build directory, represented with forward slashes.
configurations
A JSON array of entries corresponding to available build config-
urations. On single-configuration generators there is one entry
for the value of the CMAKE_BUILD_TYPE variable. For multi-con-
figuration generators there is an entry for each configuration
listed in the CMAKE_CONFIGURATION_TYPES variable. Each entry is
a JSON object containing members:
name A string specifying the name of the configuration, e.g.
Debug.
directories
A JSON array of entries each corresponding to a build
system directory whose source directory contains a CMake-
Lists.txt file. The first entry corresponds to the
top-level directory. Each entry is a JSON object con-
taining members:
source A string specifying the path to the source direc-
tory, represented with forward slashes. If the
directory is inside the top-level source directory
then the path is specified relative to that direc-
tory (with . for the top-level source directory
itself). Otherwise the path is absolute.
build A string specifying the path to the build direc-
tory, represented with forward slashes. If the
directory is inside the top-level build directory
then the path is specified relative to that direc-
tory (with . for the top-level build directory it-
self). Otherwise the path is absolute.
parentIndex
Optional member that is present when the directory
is not top-level. The value is an unsigned inte-
ger 0-based index of another entry in the main di-
rectories array that corresponds to the parent di-
rectory that added this directory as a subdirec-
tory.
childIndexes
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 add_subdirectory() or subdirs() command.
Each entry is an unsigned integer 0-based index of
another entry in the main directories array.
projectIndex
An unsigned integer 0-based index into the main
projects array indicating the build system project
to which the this directory belongs.
targetIndexes
Optional member that is present when the directory
itself has targets, excluding those belonging to
subdirectories. The value is a JSON array of en-
tries corresponding to the targets. Each entry is
an unsigned integer 0-based index into the main
targets array.
minimumCMakeVersion
Optional member present when a minimum required
version of CMake is known for the directory. This
is the <min> version given to the most local call
to the cmake_minimum_required(VERSION) command in
the directory itself or one of its ancestors. The
value is a JSON object with one member:
string A string specifying the minimum required
version in the format:
<major>.<minor>[.<patch>[.<tweak>]][<suffix>]
Each component is an unsigned integer and
the suffix may be an arbitrary string.
hasInstallRule
Optional member that is present with boolean value
true when the directory or one of its subdirecto-
ries contains any install() rules, i.e. whether a
make install or equivalent rule is available.
projects
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 CMakeLists.txt file calls the project() command
with a project name different from its parent directory.
The first entry corresponds to the top-level project.
Each entry is a JSON object containing members:
name A string specifying the name given to the
project() command.
parentIndex
Optional member that is present when the project
is not top-level. The value is an unsigned inte-
ger 0-based index of another entry in the main
projects array that corresponds to the parent
project that added this project as a sub-project.
childIndexes
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 an-
other entry in the main projects array.
directoryIndexes
A JSON array of entries corresponding to build
system directories that are part of the project.
The first entry corresponds to the top-level di-
rectory of the project. Each entry is an unsigned
integer 0-based index into the main directories
array.
targetIndexes
Optional member that is present when the project
itself has targets, excluding those belonging to
sub-projects. The value is a JSON array of en-
tries corresponding to the targets. Each entry is
an unsigned integer 0-based index into the main
targets array.
targets
A JSON array of entries corresponding to the build system
targets. Such targets are created by calls to add_exe-
cutable(), add_library(), and add_custom_target(), ex-
cluding imported targets and interface libraries (which
do not generate any build rules). Each entry is a JSON
object containing members:
name A string specifying the target name.
id A string uniquely identifying the target. This
matches the id field in the file referenced by
jsonFile.
directoryIndex
An unsigned integer 0-based index into the main
directories array indicating the build system di-
rectory in which the target is defined.
projectIndex
An unsigned integer 0-based index into the main
projects array indicating the.
CMAKE-FILE-API(7) CMake CMAKE-FILE-API(7)
NAME
cmake-file-api - CMake File-Based API
INTRODUCTION
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 Object Kinds. When CMake generates the
buildsystem in that build tree it will read the query files and write
reply files for the client to read.
The file-based API uses a <build>/.cmake/api/ 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 orthogo-
nal to the versioning of Object Kinds used in replies. This version of
CMake supports only one API version, API v1.
API V1
API v1 is housed in the <build>/.cmake/api/v1/ directory. It has the
following subdirectories:
query/ Holds query files written by clients. These may be v1 Shared
Stateless Query Files, v1 Client Stateless Query Files, or v1
Client Stateful Query Files.
reply/ Holds reply files written by CMake whenever it runs to generate
a build system. These are indexed by a v1 Reply Index File file
that may reference additional v1 Reply Files. CMake owns all
reply files. Clients must never remove them.
Clients may look for and read a reply index file at any time.
Clients may optionally create the reply/ directory at any time
and monitor it for the appearance of a new reply index file.
v1 Shared Stateless Query Files
Shared stateless query files allow clients to share requests for major
versions of the Object Kinds and get all requested versions recognized
by the CMake that runs.
Clients may create shared requests by creating empty files in the
v1/query/ directory. The form is:
<build>/.cmake/api/v1/query/<kind>-v<major>
where <kind> is one of the Object Kinds, -v is literal, and <major> is
the major version number.
Files of this form are stateless shared queries not owned by any spe-
cific client. Once created they should not be removed without external
client coordination or human intervention.
v1 Client Stateless Query Files
Client stateless query files allow clients to create owned requests for
major versions of the Object Kinds and get all requested versions rec-
ognized by the CMake that runs.
Clients may create owned requests by creating empty files in
client-specific query subdirectories. The form is:
<build>/.cmake/api/v1/query/client-<client>/<kind>-v<major>
where client- is literal, <client> is a string uniquely identifying the
client, <kind> is one of the Object Kinds, -v is literal, and <major>
is the major version number. Each client must choose a unique <client>
identifier via its own means.
Files of this form are stateless queries owned by the client <client>.
The owning client may remove them at any time.
v1 Client Stateful Query Files
Stateful query files allow clients to request a list of versions of
each of the Object Kinds and get only the most recent version recog-
nized by the CMake that runs.
Clients may create owned stateful queries by creating query.json files
in client-specific query subdirectories. The form is:
<build>/.cmake/api/v1/query/client-<client>/query.json
where client- is literal, <client> is a string uniquely identifying the
client, and query.json is literal. Each client must choose a unique
<client> identifier via its own means.
query.json files are stateful queries owned by the client <client>.
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 unnec-
essarily.
A query.json file must contain a JSON object:
{
"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": {}
}
The members are:
requests
A JSON array containing zero or more requests. Each request is
a JSON object with members:
kind Specifies one of the Object Kinds to be included in the
reply.
version
Indicates the version(s) of the object kind that the
client understands. Versions have major and minor compo-
nents following semantic version conventions. The value
must be
o a JSON integer specifying a (non-negative) major ver-
sion number, or
o a JSON object containing major and (optionally) minor
members specifying non-negative integer version compo-
nents, or
o a JSON array whose elements are each one of the above.
client Optional member reserved for use by the client. This
value is preserved in the reply written for the client in
the v1 Reply Index File but is otherwise ignored.
Clients may use this to pass custom information with a
request through to its reply.
For each requested object kind CMake will choose the first ver-
sion that it recognizes for that kind among those listed in the
request. The response will use the selected major version with
the highest minor version known to the running CMake for that
major version. Therefore clients should list all supported ma-
jor versions in preferred order along with the minimal minor
version required for each major version.
client Optional member reserved for use by the client. This value is
preserved in the reply written for the client in the v1 Reply
Index File but is otherwise ignored. Clients may use this to
pass custom information with a query through to its reply.
Other query.json top-level members are reserved for future use. If
present they are ignored for forward compatibility.
v1 Reply Index File
CMake writes an index-*.json file to the v1/reply/ directory whenever
it runs to generate a build system. Clients must read the reply index
file first and may read other v1 Reply Files only by following refer-
ences. The form of the reply index file name is:
<build>/.cmake/api/v1/reply/index-<unspecified>.json
where index- is literal and <unspecified> is an unspecified name se-
lected 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.
The reply index file contains a JSON object:
{
"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": {}
}
}
}
}
The members are:
cmake A JSON object containing information about the instance of CMake
that generated the reply. It contains members:
version
A JSON object specifying the version of CMake with mem-
bers:
major, minor, patch
Integer values specifying the major, minor, and
patch version components.
suffix A string specifying the version suffix, if any,
e.g. g0abc3.
string A string specifying the full version in the format
<major>.<minor>.<patch>[-<suffix>].
isDirty
A boolean indicating whether the version was built
from a version controlled source tree with local
modifications.
paths A JSON object specifying paths to things that come with
CMake. It has members for cmake, ctest, and cpack whose
values are JSON strings specifying the absolute path to
each tool, represented with forward slashes. It also has
a root member for the absolute path to the directory con-
taining CMake resources like the Modules/ directory (see
CMAKE_ROOT).
generator
A JSON object describing the CMake generator used for the
build. It has members:
multiConfig
A boolean specifying whether the generator sup-
ports multiple output configurations.
name A string specifying the name of the generator.
platform
If the generator supports CMAKE_GENERATOR_PLAT-
FORM, this is a string specifying the generator
platform name.
objects
A JSON array listing all versions of all Object Kinds generated
as part of the reply. Each array entry is a v1 Reply File Ref-
erence.
reply A JSON object mirroring the content of the query/ directory that
CMake loaded to produce the reply. The members are of the form
<kind>-v<major>
A member of this form appears for each of the v1 Shared
Stateless Query Files that CMake recognized as a request
for object kind <kind> with major version <major>. The
value is a v1 Reply File Reference to the corresponding
reply file for that object kind and version.
<unknown>
A member of this form appears for each of the v1 Shared
Stateless Query Files that CMake did not recognize. The
value is a JSON object with a single error member con-
taining a string with an error message indicating that
the query file is unknown.
client-<client>
A member of this form appears for each client-owned di-
rectory holding v1 Client Stateless Query Files. The
value is a JSON object mirroring the content of the
query/client-<client>/ directory. The members are of the
form:
<kind>-v<major>
A member of this form appears for each of the v1
Client Stateless Query Files that CMake recognized
as a request for object kind <kind> with major
version <major>. The value is a v1 Reply File
Reference to the corresponding reply file for that
object kind and version.
<unknown>
A member of this form appears for each of the v1
Client Stateless Query Files that CMake did not
recognize. The value is a JSON object with a sin-
gle error member containing a string with an error
message indicating that the query file is unknown.
query.json
This member appears for clients using v1 Client
Stateful Query Files. If the query.json file
failed to read or parse as a JSON object, this
member is a JSON object with a single error member
containing a string with an error message. Other-
wise, this member is a JSON object mirroring the
content of the query.json file. The members are:
client A copy of the query.json file client mem-
ber, if it exists.
requests
A copy of the query.json file requests mem-
ber, if it exists.
responses
If the query.json file requests member is
missing or invalid, this member is a JSON
object with a single error member contain-
ing a string with an error message. Other-
wise, this member contains a JSON array
with a response for each entry of the re-
quests array, in the same order. Each re-
sponse is
o a JSON object with a single error member
containing a string with an error mes-
sage, or
o a v1 Reply File Reference to the corre-
sponding reply file for the requested ob-
ject kind and selected version.
After reading the reply index file, clients may read the other v1 Reply
Files it references.
v1 Reply File Reference
The reply index file represents each reference to another reply file
using a JSON object with members:
kind A string specifying one of the Object Kinds.
version
A JSON object with members major and minor specifying integer
version components of the object kind.
jsonFile
A JSON string specifying a path relative to the reply index file
to another JSON file containing the object.
v1 Reply Files
Reply files containing specific Object Kinds are written by CMake. The
names of these files are unspecified and must not be interpreted by
clients. Clients must first read the v1 Reply Index File and and fol-
low references to the names of the desired response objects.
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 re-
ply. However, after generating a new reply CMake will attempt to re-
move 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 re-
ply. The client may simply start again by reading the new reply index
file.
OBJECT KINDS
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 mi-
nor components. Every kind of object has the form:
{
"kind": "<kind>",
"version": { "major": 1, "minor": 0 },
"...": {}
}
The kind member is a string specifying the object kind name. The ver-
sion member is a JSON object with major and minor members specifying
integer components of the object kinds version. Additional top-level
members are specific to each object kind.
Object Kind codemodel
The codemodel object kind describes the build system structure as mod-
eled by CMake.
There is only one codemodel object major version, version 2. Version 1
does not exist to avoid confusion with that from cmake-server(7) mode.
codemodel version 2
codemodel object version 2 is a JSON object:
{
"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>"
}
]
}
]
}
The members specific to codemodel objects are:
paths A JSON object containing members:
source A string specifying the absolute path to the top-lev
3.18.4 September 13, 2021 CMAKE-FILE-API(7)
Czas wygenerowania: 0.00055 sek.
Created with the man page lookup class by Andrew Collington.
Based on a C man page viewer by Vadim Pavlov
Unicode soft-hyphen fix (as used by RedHat) by Dan Edwards
Some optimisations by Eli Argon
Caching idea and code contribution by James Richardson
Copyright © 2003-2025 Linux.pl
Hosted by Hosting Linux.pl