cmake 文件应用编程接口(7)

介绍

CMake 提供了一个基于文件的 API，客户端可以使用它来获取有关 CMake 生成的构建系统的语义信息。客户端可以通过将查询文件写入构建树中的特定位置来使用 API，以请求零个或多个“对象种类”。当 CMake 在该构建树中生成构建系统时，它将读取查询文件并写入回复文件以供客户端读取。

基于文件的 API 使用构建树顶部的 <build>/.cmake/api/ 目录。 API 版本化以支持更改 API 目录中的文件布局。 API 文件布局版本控制与回复中使用的“对象种类”版本控制是正交的。这个版本的 CMake 只支持一个 API 版本，API v1。

API v1

API v1 位于 <build>/.cmake/api/v1/ 目录中。它有以下子目录：

查询/

保存由客户端编写的查询文件。这些可能是“v1 共享无状态查询文件”、“v1 客户端无状态查询文件”或“v1 客户端有状态查询文件”。

回复/

每当它运行以生成构建系统时，保存由 CMake 编写的回复文件。这些由 v1 Reply Index File 文件索引，该文件可能引用其他 v1 Reply Files。 CMake 拥有所有回复文件。客户绝不能删除它们。

客户可以随时查找和阅读回复索引文件。客户端可以随时选择创建``reply/`` 目录并监视它是否出现新的回复索引文件。

v1 共享无状态查询文件

共享的无状态查询文件允许客户端共享对“对象种类”的主要版本的请求，并获得运行的 CMake 识别的所有请求版本。

客户端可以通过在“v1/query/”目录中创建空文件来创建共享请求。形式是：

<build>/.cmake/api/v1/query/<kind>-v<major>

其中``<kind>``是`Object Kinds`_之一，``-v``是文字，``<major>``是主版本号。

这种形式的文件是不属于任何特定客户端的无状态共享查询。一旦创建，在没有外部客户协调或人工干预的情况下，不应删除它们。

v1 客户端无状态查询文件

客户端无状态查询文件允许客户端为“对象种类”的主要版本创建拥有的请求，并获取运行的 CMake 识别的所有请求版本。

客户端可以通过在特定于客户端的查询子目录中创建空文件来创建拥有的请求。形式是：

<build>/.cmake/api/v1/query/client-<client>/<kind>-v<major>

其中``client-是文字，``<client>``是唯一标识客户端的字符串，``<kind>``是`Object Kinds`_之一，-v``是文字, <major> 是主版本号。每个客户端必须通过自己的方式选择一个唯一的“<client>”标识符。

这种形式的文件是客户端 <client> 拥有的无状态查询。拥有的客户可以随时删除它们。

v1 客户端状态查询文件

有状态查询文件允许客户端请求每个“对象种类”的版本列表，并仅获取运行的 CMake 识别的最新版本。

客户端可以通过在特定于客户端的查询子目录中创建“query.json”文件来创建自有状态查询。形式是：

<build>/.cmake/api/v1/query/client-<client>/query.json

其中``client-``是文字，``<client>``是唯一标识客户端的字符串，``query.json``是文字。每个客户端必须通过自己的方式选择一个唯一的“<client>”标识符。

query.json 文件是客户端 <client> 拥有的状态查询。拥有的客户可以随时更新或删除它们。当给定的客户端安装更新时，它可能会更新它为构建树而编写的有状态查询，以请求更新的对象版本。这可用于避免要求 CMake 不必要地生成多个对象版本。

query.json 文件必须包含一个 JSON 对象：

{
  "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": {}
}

成员是：

请求

包含零个或多个请求的 JSON 数组。每个请求都是一个包含成员的 JSON 对象：

善良

指定要包含在回复中的“对象种类”之一。

版本

指示客户端理解的对象种类的版本。版本具有遵循语义版本约定的主要和次要组件。该值必须是

• 指定（非负）主要版本号的 JSON 整数，或

• 包含指定非负整数版本组件的``major``和（可选）``minor``成员的JSON对象，或

• 一个 JSON 数组，其元素均为上述各项。

客户端

保留供客户端使用的可选成员。此值保留在为客户端编写的回复中，位于“v1 回复索引文件”中，但会被忽略。客户可以使用它来将自定义信息与请求一起传递到其回复。

对于每个请求的对象种类，CMake 将在请求中列出的那些中选择它为该种类识别的*第一个*版本。响应将使用选定的*主要*版本和运行中的 CMake 已知的最高*次要*版本。因此，客户应按首选顺序列出所有受支持的主要版本以及每个主要版本所需的最小次要版本。

客户端

保留供客户端使用的可选成员。此值保留在为客户端编写的回复中，位于“v1 回复索引文件”中，但会被忽略。客户端可以使用它来将自定义信息与查询一起传递到其回复。

其他 query.json 顶级成员保留供将来使用。如果存在，它们将被忽略以实现向前兼容性。

v1 回复索引文件

CMake 在运行时将一个 index-*.json 文件写入 v1/reply/ 目录以生成构建系统。客户端必须先阅读回复索引文件，然后才能阅读其他`v1 回复文件`_ 只能通过以下参考。回复索引文件名的格式为：：

<build>/.cmake/api/v1/reply/index-<unspecified>.json

其中 index- 是文字，<unspecified> 是 CMake 选择的未指定名称。每当生成一个新的索引文件时，它都会被赋予一个新名称，并且任何旧的都会被删除。在这些步骤之间的短时间内，可能存在多个索引文件；字典序中名称最大的是当前索引文件。

回复索引文件包含一个 JSON 对象：

{
  "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": {}
      }
    }
  }
}

成员是：

cmake

一个 JSON 对象，其中包含有关生成回复的 CMake 实例的信息。它包含成员：

版本

一个 JSON 对象，指定带有成员的 CMake 版本：

主要，次要，补丁

指定主要、次要和补丁版本组件的整数值。

后缀

指定版本后缀的字符串（如果有），例如``g0abc3``。

字符串

以“<major>.<minor>.<patch>[-<suffix>]”格式指定完整版本的字符串。

是脏的

一个布尔值，指示该版本是否是从具有本地修改的版本控制源代码树构建的。

路径

一个 JSON 对象，指定 CMake 附带的内容的路径。它有 cmake、 ctest 和 cpack 的成员，它们的值是 JSON 字符串，指定每个工具的绝对路径，用正斜杠表示。它还有一个 root 成员，用于包含 CMake 资源的目录的绝对路径，例如 Modules/ 目录（参见 CMAKE_ROOT）。

生成器

描述用于构建的 CMake 生成器的 JSON 对象。它有成员：

多配置

一个布尔值，指定生成器是否支持多个输出配置。

名字

指定生成器名称的字符串。

平台

如果生成器支持 CMAKE_GENERATOR_PLATFORM，这是一个指定生成器平台名称的字符串。

对象

一个 JSON 数组，列出作为回复的一部分生成的所有“对象种类”的所有版本。每个数组条目都是一个 v1 Reply File Reference。

回复

一个 JSON 对象，反映了 CMake 加载以生成回复的 query/ 目录的内容。成员的形式

<种类>-v<主要>

这种形式的成员出现在每个 v1 共享无状态查询文件 中，CMake 将其识别为对具有主要版本``<major>`` 的对象种类``<kind>`` 的请求。该值是该对象种类和版本的相应回复文件的“v1 回复文件参考”。

<未知>

对于 CMake 无法识别的每个“v1 共享无状态查询文件”，都会出现此表单的成员。该值是一个 JSON 对象，具有单个 error 成员，其中包含一个字符串，其中包含一条错误消息，指示查询文件未知。

客户端-<客户端>

对于每个持有“v1 客户端无状态查询文件”的客户端拥有的目录，都会出现此表单的成员。该值是一个 JSON 对象，反映了 query/client-<client>/ 目录的内容。成员的形式为：

<种类>-v<主要>

这种形式的成员出现在每个 v1 客户端无状态查询文件 中，CMake 将其识别为对具有主要版本``<major>`` 的对象种类``<kind>`` 的请求。该值是该对象种类和版本的相应回复文件的“v1 回复文件参考”。

<未知>

对于 CMake 无法识别的每个“v1 客户端无状态查询文件”，都会出现此表单的成员。该值是一个 JSON 对象，具有单个 error 成员，其中包含一个字符串，其中包含一条错误消息，指示查询文件未知。

query.json

该成员为使用“v1 客户端状态查询文件”的客户端显示。如果 query.json 文件无法读取或解析为 JSON 对象，则此成员是一个 JSON 对象，带有一个包含带有错误消息的字符串的 error 成员。否则，该成员是一个镜像 query.json 文件内容的 JSON 对象。成员是：

客户端

query.json 文件``client`` 成员的副本（如果存在）。

请求

query.json 文件``requests`` 成员的副本（如果存在）。

回应

如果 query.json 文件 requests 成员丢失或无效，则此成员是一个 JSON 对象，带有一个包含带有错误消息的字符串的 error 成员。否则，此成员包含一个 JSON 数组，其中包含对“请求”数组的每个条目的响应，顺序相同。每个响应是

• 一个带有单个 error 成员的 JSON 对象，其中包含带有错误消息的字符串，或者

• v1 Reply File Reference 到请求的对象类型和所选版本的相应回复文件。

读取回复索引文件后，客户端可以读取它引用的其他“v1 回复文件”。

v1 回复文件参考

回复索引文件使用带有成员的 JSON 对象表示对另一个回复文件的每个引用：

善良

指定“对象种类”之一的字符串。

版本

一个 JSON 对象，其成员 major 和 minor 指定对象种类的整数版本组件。

jsonFile

一个 JSON 字符串，指定相对于包含该对象的另一个 JSON 文件的回复索引文件的路径。

v1 回复文件

包含特定“对象种类”的回复文件由 CMake 编写。这些文件的名称未指定，不能由客户端解释。客户端必须首先阅读`v1 回复索引文件`_ 并遵循对所需响应对象名称的引用。

回复文件（包括索引文件）永远不会被同名不同内容的文件替换。这允许客户端与正在运行的可能生成新回复的 CMake 同时读取文件。然而，在生成一个新的回复后，CMake 将尝试从以前的运行中删除它不只是写入的回复文件。如果客户端尝试读取索引引用的回复文件但发现文件丢失，则意味着并发 CMake 已生成新回复。客户端可以简单地通过读取新的回复索引文件重新开始。

对象种类

CMake 基于文件的 API 使用以下类型的 JSON 对象报告有关构建系统的语义信息。每种对象都使用主要和次要组件的语义版本控制独立进行版本控制。每种对象都有以下形式：

{
  "kind": "<kind>",
  "version": { "major": 1, "minor": 0 },
  "...": {}
}

kind 成员是指定对象种类名称的字符串。 version 成员是一个 JSON 对象，其中``major`` 和``minor`` 成员指定对象种类版本的整数部分。其他顶级成员特定于每个对象种类。

对象种类“代码模型”

codemodel 对象类型描述了由 CMake 建模的构建系统结构。

只有一个 codemodel 对象主要版本，版本 2。版本 1 不存在以避免与来自 cmake-server(7) 模式的混淆。

“代码模型”版本 2

codemodel 对象版本 2 是一个 JSON 对象：

{
  "kind": "codemodel",
  "version": { "major": 2, "minor": 5 },
  "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"
          },
          "jsonFile": "<file>"
        },
        {
          "source": "sub",
          "build": "sub",
          "parentIndex": 0,
          "projectIndex": 0,
          "targetIndexes": [ 1 ],
          "minimumCMakeVersion": {
            "string": "3.14"
          },
          "jsonFile": "<file>"
        }
      ],
      "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>"
        }
      ]
    }
  ]
}

codemodel 对象特有的成员是：

路径

包含成员的 JSON 对象：

来源

一个字符串，指定顶级源目录的绝对路径，用正斜杠表示。

构建

一个字符串，指定顶级构建目录的绝对路径，用正斜杠表示。

配置

对应于可用构建配置的条目的 JSON 数组。在单配置生成器上，CMAKE_BUILD_TYPE 变量的值有一个条目。对于多配置生成器，CMAKE_CONFIGURATION_TYPES 变量中列出的每个配置都有一个条目。每个条目都是一个包含成员的 JSON 对象：

名字

指定配置名称的字符串，例如``调试``。

目录

条目的 JSON 数组，每个条目对应于构建系统目录，其源目录包含一个“CMakeLists.txt”文件。第一个条目对应于顶级目录。每个条目都是一个包含成员的 JSON 对象：

来源

指定源目录路径的字符串，用正斜杠表示。如果该目录位于顶级源目录中，则路径是相对于该目录指定的（顶级源目录本身带有 .）。否则路径是绝对的。

构建

指定构建目录路径的字符串，用正斜杠表示。如果该目录位于顶级构建目录中，则路径是相对于该目录指定的（顶级构建目录本身使用 .）。否则路径是绝对的。

父索引

当目录不是顶级目录时出现的可选成员。该值是主“directories”数组中另一个条目的基于 0 的无符号整数索引，该数组对应于将此目录添加为子目录的父目录。

childIndexes

当目录具有子目录时存在的可选成员。该值是一个 JSON 条目数组，对应于由 add_subdirectory() 或 subdirs() 命令创建的子目录。每个条目都是主“目录”数组中另一个条目的从 0 开始的无符号整数索引。

projectIndex

主“projects”数组中基于 0 的无符号整数索引，指示此目录所属的构建系统项目。

目标索引

当目录本身具有目标时存在的可选成员，不包括属于子目录的目标。该值是与目标对应的条目的 JSON 数组。每个条目都是一个无符号整数，从 0 开始索引到主“目标”数组中。

最小CMakeVersion

当目录已知最低要求的 CMake 版本时，可选成员出现。这是给予目录本身或其祖先之一的 cmake_minimum_required(VERSION) 命令的最本地调用的 <min> 版本。该值是一个具有一个成员的 JSON 对象：

字符串

指定最低要求版本的字符串，格式如下：

<major>.<minor>[.<patch>[.<tweak>]][<suffix>]

每个组件都是一个无符号整数，后缀可以是任意字符串。

有安装规则

当目录或其子目录之一包含任何 install() 规则时，布尔值 true 的可选成员，即是否有 make install 或等效规则可用。

jsonFile

一个 JSON 字符串，指定相对于代码模型文件到另一个包含“代码模型”版本 2“目录”对象的 JSON 文件的路径。

该字段是在代码模型版本 2.3 中添加的。

项目

对应于构建系统中定义的顶级项目和子项目的 JSON 条目数组。每个（子）项目对应一个源目录，其 CMakeLists.txt 文件调用 project() 命令，项目名称不同于其父目录。第一个条目对应于顶级项目。

每个条目都是一个包含成员的 JSON 对象：

名字

指定给 project() 命令的名称的字符串。

父索引

当项目不是顶级项目时出现的可选成员。该值是主 projects 数组中另一个条目的基于 0 的无符号整数索引，对应于将此项目添加为子项目的父项目。

childIndexes

当项目有子项目时出现的可选成员。该值是与子项目对应的条目的 JSON 数组。每个条目都是主 projects 数组中另一个条目的无符号整数，从 0 开始的索引。

目录索引

条目的 JSON 数组，对应于作为项目一部分的构建系统目录。第一个条目对应于项目的顶级目录。每个条目都是一个无符号整数，从 0 开始索引到主“目录”数组中。

目标索引

当项目本身有目标时存在的可选成员，不包括属于子项目的目标。该值是与目标对应的条目的 JSON 数组。每个条目都是一个无符号整数，从 0 开始索引到主“目标”数组中。

目标

与构建系统目标对应的条目的 JSON 数组。此类目标是通过调用 add_executable()、 add_library() 和 add_custom_target() 创建的，不包括导入的目标和接口库（不生成任何构建规则）。每个条目都是一个包含成员的 JSON 对象：

名字

指定目标名称的字符串。

id

唯一标识目标的字符串。这与 jsonFile 引用的文件中的 id 字段相匹配。

目录索引

主“目录”数组中基于 0 的无符号整数索引，指示定义目标的构建系统目录。

projectIndex

主“projects”数组中基于 0 的无符号整数索引，指示定义目标的构建系统项目。

jsonFile

一个 JSON 字符串，指定相对于代码模型文件到另一个包含“代码模型”版本 2“目标”对象的 JSON 文件的路径。

“代码模型”版本 2“目录”对象

代码模型“目录”对象由“代码模型”第 2 版对象的“目录”数组引用。每个“目录”对象都是一个具有成员的 JSON 对象：

路径

包含成员的 JSON 对象：

来源

指定源目录路径的字符串，用正斜杠表示。如果该目录位于顶级源目录中，则路径是相对于该目录指定的（顶级源目录本身带有 .）。否则路径是绝对的。

构建

指定构建目录路径的字符串，用正斜杠表示。如果该目录位于顶级构建目录中，则路径是相对于该目录指定的（顶级构建目录本身使用 .）。否则路径是绝对的。

安装程序

对应于 install() 规则的条目的 JSON 数组。每个条目都是一个包含成员的 JSON 对象：

组件

一个字符串，指定由相应的 install() 命令调用选择的组件。

目的地

对于下面的特定 type 值存在的可选成员。该值是一个字符串，指定安装目标路径。该路径可以是绝对路径，也可以是相对于安装前缀的路径。

路径

对于下面的特定 type 值存在的可选成员。该值是与要安装的路径（文件或目录）对应的条目的 JSON 数组。每个条目都是以下之一：

• 一个字符串，指定要从中安装文件或目录的路径。前面没有“/”的路径部分还指定了目标下文件或目录要安装到的路径（名称）。

• 具有成员的 JSON 对象：

  来自

  一个字符串，指定要从中安装文件或目录的路径。

  到

  一个字符串，指定目标下要安装的文件或目录的路径。

在这两种情况下，路径都用正斜杠表示。如果“from”路径位于相应“type”值记录的顶级目录内，则路径是相对于该目录指定的。否则路径是绝对的。

类型

指定安装规则类型的字符串。该值是以下之一，一些变体提供额外的成员：

文件

install(FILES) 或 install(PROGRAMS) 调用。 destination 和 paths 成员被填充，顶级 source 目录下的路径相对于它表示。 isOptional 成员可能存在。此类型没有其他成员。

目录

install(DIRECTORY) 调用。 destination 和 paths 成员被填充，顶级 source 目录下的路径相对于它表示。 isOptional 成员可能存在。此类型没有其他成员。

目标

install(TARGETS) 调用。 destination 和 paths 成员被填充，顶级 build 目录下的路径相对于它表示。 isOptional 成员可能存在。这种类型有额外的成员``targetId``、targetIndex、targetIsImportLibrary 和``targetInstallNamelink``。

出口

install(EXPORT) 调用。 destination 和 paths 成员被填充，顶级 build 目录下的路径相对于它表示。 paths 条目指的是 CMake 为安装自动生成的文件，它们的实际值被认为是私有实现细节。这种类型有额外的成员 exportName 和 exportTargets。

脚本

install(SCRIPT) 调用。这种类型有额外的成员``scriptFile``。

代码

install(CODE) 调用。此类型没有其他成员。

importedRuntimeArtifacts

install(IMPORTED_RUNTIME_ARTIFACTS) 调用。 destination 成员被填充。 isOptional 成员可能存在。此类型没有其他成员。

runtimeDependencySet

install(RUNTIME_DEPENDENCY_SET) 调用或带有 RUNTIME_DEPENDENCIES 的 install(TARGETS) 调用。 destination 成员被填充。这种类型有额外的成员``runtimeDependencySetName`` 和``runtimeDependencySetType``。

文件集

使用 FILE_SET 的 install(TARGETS) 调用。 destination 和 paths 成员被填充。 isOptional 成员可能存在。这种类型有额外的成员``fileSetName``、fileSetType、fileSetDirectories 和``fileSetTarget``。

此类型是在代码模型版本 2.4 中添加的。

isExcludeFromAll

当使用 EXCLUDE_FROM_ALL 选项调用 install() 时，可选成员以布尔值 true 出现。

isForAllComponents

当使用 ALL_COMPONENTS 选项调用 install(SCRIPT|CODE) 时，布尔值 true 的可选成员。

是可选的

当使用 OPTIONAL 选项调用 install() 时，可选成员以布尔值 true 出现。当“类型”是“文件”、“目录”或“目标”时，这是允许的。

targetId

当``type`` 为``target`` 时存在的可选成员。该值是唯一标识要安装的目标的字符串。这与主“codemodel”对象的“targets”数组中目标的“id”成员匹配。

目标索引

当``type`` 为``target`` 时存在的可选成员。该值是一个无符号整数，从 0 开始索引到要安装的目标的主要“codemodel”对象的“targets”数组中。

targetIsImportLibrary

当``type`` 为``target`` 且安装程序用于Windows DLL 导入库文件或AIX 链接器导入文件时出现的可选成员。如果存在，它具有布尔值“true”。

targetInstallNamelink

当 type 为 target 并且安装程序对应于可以使用符号链接来实现 VERSION 和 SOVERSION 目标属性时出现的可选成员。该值是一个字符串，指示安装程序应如何处理符号链接：skip 表示安装程序应跳过符号链接并仅安装真实文件，而``only`` 表示安装程序应仅安装符号链接和不是真正的文件。在所有情况下，paths 成员都会列出它实际安装的内容。

导出名称

当``type`` 为``export`` 时存在的可选成员。该值是一个字符串，指定导出的名称。

导出目标

当``type`` 为``export`` 时存在的可选成员。该值是与导出中包含的目标对应的条目的 JSON 数组。每个条目都是一个包含成员的 JSON 对象：

id

唯一标识目标的字符串。这与主“codemodel”对象的“targets”数组中目标的“id”成员匹配。

索引

目标的主“codemodel”对象的“targets”数组中基于 0 的无符号整数索引。

runtimeDependencySetName

当 type 为 runtimeDependencySet 且安装程序由 install(RUNTIME_DEPENDENCY_SET) 调用创建时出现的可选成员。该值是一个字符串，指定已安装的运行时依赖集的名称。

runtimeDependencySetType

当``type`` 为``runtimeDependencySet`` 时存在的可选成员。该值是具有以下值之一的字符串：

图书馆

表示此安装程序安装的依赖项不是 macOS 框架。

框架

表示此安装程序安装的依赖项是 macOS 框架。

文件集名称

当``type`` 为``fileSet`` 时存在的可选成员。该值是一个带有文件集名称的字符串。

此字段是在代码模型版本 2.4 中添加的。

文件集类型

当``type`` 为``fileSet`` 时存在的可选成员。该值是一个带有文件集类型的字符串。

此字段是在代码模型版本 2.4 中添加的。

文件集目录

当``type`` 为``fileSet`` 时存在的可选成员。该值是包含文件集基本目录的字符串列表（由 HEADER_DIRS 或 HEADER_DIRS_<NAME> 的 genex 评估确定）。

此字段是在代码模型版本 2.4 中添加的。

文件设置目标

当``type`` 为``fileSet`` 时存在的可选成员。该值是一个具有成员的 JSON 对象：

id

唯一标识目标的字符串。这与主“codemodel”对象的“targets”数组中目标的“id”成员匹配。

索引

目标的主“codemodel”对象的“targets”数组中基于 0 的无符号整数索引。

此字段是在代码模型版本 2.4 中添加的。

脚本文件

当 type 为 script 时出现的可选成员。该值是一个字符串，指定磁盘上脚本文件的路径，用正斜杠表示。如果文件位于顶级源目录中，则路径是相对于该目录指定的。否则路径是绝对的。

回溯

当 CMake 语言回溯到 install() 或添加此安装程序的其他命令调用可用时出现的可选成员。该值是“backtraceGraph”成员的“nodes”数组中基于 0 的无符号整数索引。

回溯图

“codemodel”版本 2“回溯图” 其节点从该“目录”对象中其他地方的 backtrace 成员引用。

“代码模型”版本 2“目标”对象

代码模型“目标”对象由“代码模型”第 2 版对象的“目标”数组引用。每个“目标”对象都是一个具有成员的 JSON 对象：

名字

一个字符串，指定目标的逻辑名称。

id

唯一标识目标的字符串。格式未指定，客户不应解释。

类型

指定目标类型的字符串。该值为 EXECUTABLE、STATIC_LIBRARY、SHARED_LIBRARY、MODULE_LIBRARY、OBJECT_LIBRARY、INTERFACE_LIBRARY 或 UTILITY 之一。

回溯

当对创建目标的源代码中的命令的 CMake 语言回溯可用时出现的可选成员。该值是“backtraceGraph”成员的“nodes”数组中基于 0 的无符号整数索引。

文件夹

设置 FOLDER 目标属性时出现的可选成员。该值是一个具有一个成员的 JSON 对象：

名字

指定目标文件夹名称的字符串。

路径

包含成员的 JSON 对象：

来源

指定目标源目录路径的字符串，用正斜杠表示。如果该目录位于顶级源目录中，则路径是相对于该目录指定的（顶级源目录本身带有 .）。否则路径是绝对的。

构建

指定目标构建目录路径的字符串，用正斜杠表示。如果该目录位于顶级构建目录中，则路径是相对于该目录指定的（顶级构建目录本身使用 .）。否则路径是绝对的。

nameOnDisk

对于链接或归档到单个主要工件中的可执行文件和库目标，存在的可选成员。该值是一个字符串，指定磁盘上该工件的文件名。

人工制品

存在于可执行文件和库目标的可选成员，这些目标在磁盘上生成供依赖者使用的工件。该值是与工件对应的条目的 JSON 数组。每个条目都是一个包含一个成员的 JSON 对象：

路径

指定磁盘上文件路径的字符串，用正斜杠表示。如果文件位于顶级构建目录中，则路径是相对于该目录指定的。否则路径是绝对的。

isGeneratorProvided

如果目标是由 CMake 的构建系统生成器而不是源代码中的命令提供的，则可选成员具有布尔值“true”。

安装

当目标具有 install() 规则时出现的可选成员。该值是一个具有成员的 JSON 对象：

前缀

指定安装前缀的 JSON 对象。它有一个成员：

路径

指定 CMAKE_INSTALL_PREFIX 值的字符串。

目的地

指定安装目标路径的 JSON 条目数组。每个条目都是一个包含成员的 JSON 对象：

路径

指定安装目标路径的字符串。该路径可以是绝对路径，也可以是相对于安装前缀的路径。

回溯

当 CMake 语言回溯到指定此目标的 install() 命令调用可用时出现的可选成员。该值是“backtraceGraph”成员的“nodes”数组中基于 0 的无符号整数索引。

链接

存在于链接到运行时二进制文件的可执行文件和共享库目标的可选成员。该值是一个 JSON 对象，其成员描述链接步骤：

语言

指定工具链语言（例如“C”、“CXX”、“Fortran”）的字符串用于调用链接器。

commandFragments

当链接命令行调用的片段可用时出现的可选成员。该值是指定有序片段的 JSON 条目数组。每个条目都是一个包含成员的 JSON 对象：

片段

指定链接命令行调用片段的字符串。该值以构建系统的本机 shell 格式编码。

作用

指定片段内容角色的字符串：

• flags：链接标志。

• libraries：链接库文件路径或标志。

• libraryPath：库搜索路径标志。

• frameworkPath：macOS 框架搜索路径标志。

lto

启用链接时优化（也称为过程间优化或链接时代码生成）时，以布尔值“true”存在的可选成员。

系统根

定义 CMAKE_SYSROOT_LINK 或 CMAKE_SYSROOT 变量时出现的可选成员。该值是一个具有一个成员的 JSON 对象：

路径

一个字符串，指定 sysroot 的绝对路径，用正斜杠表示。

存档

静态库目标的可选成员。该值是一个 JSON 对象，其成员描述了归档步骤：

commandFragments

当归档程序命令行调用的片段可用时出现的可选成员。该值是指定片段的 JSON 条目数组。每个条目都是一个包含成员的 JSON 对象：

片段

指定归档程序命令行调用片段的字符串。该值以构建系统的本机 shell 格式编码。

作用

指定片段内容角色的字符串：

• flags：归档器标志。

lto

启用链接时优化（也称为过程间优化或链接时代码生成）时，以布尔值“true”存在的可选成员。

依赖关系

当目标依赖于其他目标时出现的可选成员。该值是与依赖项对应的条目的 JSON 数组。每个条目都是一个包含成员的 JSON 对象：

id

唯一标识此目标所依赖的目标的字符串。这与另一个目标的主要 id 成员相匹配。

回溯

当 CMake 语言回溯到 add_dependencies()、 target_link_libraries() 或创建此依赖项的其他命令调用可用时存在的可选成员。该值是“backtraceGraph”成员的“nodes”数组中基于 0 的无符号整数索引。

文件集

对应于目标文件集的条目的 JSON 数组。每个条目都是一个包含成员的 JSON 对象：

名字

指定文件集名称的字符串。

类型

指定文件集类型的字符串。请参阅 target_sources() 支持的文件集类型。

可见性

指定文件集可见性的字符串； PUBLIC、PRIVATE 或 INTERFACE 之一。

基础目录

一个 JSON 字符串数组，指定包含文件集中源的基本目录。

该字段是在代码模型版本 2.5 中添加的。

来源

对应于目标源文件的条目的 JSON 数组。每个条目都是一个包含成员的 JSON 对象：

路径

指定磁盘上源文件路径的字符串，用正斜杠表示。如果文件位于顶级源目录中，则路径是相对于该目录指定的。否则路径是绝对的。

compileGroupIndex

编译源时出现的可选成员。该值是“compileGroups”数组中基于 0 的无符号整数索引。

sourceGroupIndex

通过 source_group() 命令或默认情况下，当源是源组的一部分时存在的可选成员。该值是 sourceGroups 数组中基于 0 的无符号整数索引。

isGenerated

如果源是:prop_sf:GENERATED，则可选成员以布尔值``true``存在。

文件集索引

当源是文件集的一部分时出现的可选成员。该值是 fileSets 数组中基于 0 的无符号整数索引。

该字段是在代码模型版本 2.5 中添加的。

回溯

当 CMake 语言回溯到 target_sources()、 add_executable()、 add_library()、 add_custom_target() 或将此源添加到目标可用。该值是“backtraceGraph”成员的“nodes”数组中基于 0 的无符号整数索引。

``源组`​​`

当源通过 source_group() 命令或默认情况下分组在一起时出现的可选成员。该值是与组对应的条目的 JSON 数组。每个条目都是一个包含成员的 JSON 对象：

名字

指定源组名称的字符串。

sourceIndexes

列出属于该组的源的 JSON 数组。每个条目都是一个无符号整数，从 0 开始索引到目标的主要“sources”数组中。

编译组

当目标具有编译源时出现的可选成员。该值是一个 JSON 条目数组，对应于所有使用相同设置编译的源组。每个条目都是一个包含成员的 JSON 对象：

sourceIndexes

列出属于该组的源的 JSON 数组。每个条目都是一个无符号整数，从 0 开始索引到目标的主要“sources”数组中。

语言

指定工具链语言（例如“C”、“CXX”、“Fortran”）的字符串用于编译源文件。

语言标准

显式设置语言标准（例如通过 CXX_STANDARD）或通过编译功能隐式设置时出现的可选成员。每个条目都是一个具有两个成员的 JSON 对象：

回溯

当 CMake 语言回溯到 <LANG>_STANDARD 设置可用时出现的可选成员。如果语言标准是由编译特性隐式设置的，则这些标准将用作回溯。多个编译功能可能需要相同的语言标准，因此可能会有多个回溯。该值是一个 JSON 数组，每个条目都是一个无符号整数，从 0 开始索引到 backtraceGraph` 成员的 nodes 数组。

标准

表示语言标准的字符串。

此字段是在代码模型版本 2.2 中添加的。

compileCommandFragments

当编译器命令行调用的片段可用时出现的可选成员。该值是指定有序片段的 JSON 条目数组。每个条目都是一个具有一个成员的 JSON 对象：

片段

指定编译命令行调用片段的字符串。该值以构建系统的本机 shell 格式编码。

包括

包含目录时存在的可选成员。该值是一个 JSON 数组，每个目录都有一个条目。每个条目都是一个包含成员的 JSON 对象：

路径

指定包含目录路径的字符串，用正斜杠表示。

isSystem

如果包含目录被标记为系统包含目录，则可选成员以布尔值“true”存在。

回溯

当 CMake 语言回溯到 target_include_directories() 或添加此包含目录的其他命令调用可用时存在的可选成员。该值是“backtraceGraph”成员的“nodes”数组中基于 0 的无符号整数索引。

precompileHeaders

当 target_precompile_headers() 或其他命令调用在目标上设置 PRECOMPILE_HEADERS 时存在的可选成员。该值是一个 JSON 数组，每个标头都有一个条目。每个条目都是一个包含成员的 JSON 对象：

标题

预编译头文件的完整路径。

回溯

当 CMake 语言回溯到 target_precompile_headers() 或添加此预编译标头的其他命令调用可用时存在的可选成员。该值是“backtraceGraph”成员的“nodes”数组中基于 0 的无符号整数索引。

此字段是在代码模型版本 2.1 中添加的。

定义

存在预处理器定义时存在的可选成员。该值是一个 JSON 数组，每个定义都有一个条目。每个条目都是一个包含成员的 JSON 对象：

定义

以“<name>[=<value>]”格式指定预处理器定义的字符串，例如``DEF`` 或 DEF=1。

回溯

当 CMake 语言回溯到 target_compile_definitions() 或添加此预处理器定义的其他命令调用可用时存在的可选成员。该值是“backtraceGraph”成员的“nodes”数组中基于 0 的无符号整数索引。

系统根

定义 CMAKE_SYSROOT_COMPILE 或 CMAKE_SYSROOT 变量时出现的可选成员。该值是一个具有一个成员的 JSON 对象：

路径

一个字符串，指定 sysroot 的绝对路径，用正斜杠表示。

回溯图

“codemodel”版本 2“回溯图” 其节点从该“目标”对象中其他地方的 backtrace 成员引用。

“代码模型”版本 2“回溯图”

“codemodel”第 2 版“目录”对象或“codemodel”第 2 版“目标”对象的 ``backtraceGraph 成员是描述回溯图的 JSON 对象。它的节点是从包含对象中其他地方的“backtrace”成员引用的。回溯图对象成员是：

节点

一个 JSON 数组，列出回溯图中的节点。每个条目都是一个包含成员的 JSON 对象：

文件

回溯“文件”数组中基于 0 的无符号整数索引。

线

当节点代表文件中的一行时出现的可选成员。该值是一个无符号整数，从 1 开始的行号。

命令

当节点表示文件中的命令调用时出现的可选成员。该值是回溯“commands”数组中基于 0 的无符号整数索引。

父母

当节点不在调用堆栈底部时出现的可选成员。该值是回溯“节点”数组中另一个条目的从 0 开始的无符号整数索引。

命令

一个 JSON 数组，列出回溯节点引用的命令名称。每个条目都是一个指定命令名称的字符串。

文件

列出回溯节点引用的 CMake 语言文件的 JSON 数组。每个条目都是一个字符串，指定文件的路径，用正斜杠表示。如果文件位于顶级源目录中，则路径是相对于该目录指定的。否则路径是绝对的。

对象种类“configureLog”

configureLog 对象类型描述了 cmake-configure-log(7) 文件的位置和内容。

只有一个 configureLog 对象主要版本，版本 1。

“配置日志”版本 1

configureLog 对象版本 1 是一个 JSON 对象：

{
  "kind": "configureLog",
  "version": { "major": 1, "minor": 0 },
  "path": "/path/to/top-level-build-dir/CMakeFiles/CMakeConfigureLog.yaml",
  "eventKindNames": [ "try_compile-v1", "try_run-v1" ]
}

configureLog 对象特有的成员是：

路径

指定配置日志文件路径的字符串。客户端必须从此路径读取日志文件，该路径可能与 cmake-configure-log(7) 记录的路径不同。如果没有记录任何事件，则日志文件可能不存在。

eventKindNames

一个 JSON 数组，其每个条目都是一个 JSON 字符串，命名 cmake-configure-log(7) 版本化事件类型之一。最多将列出每种配置日志事件类型的一个版本。尽管配置日志可能包含其他（版本化的）事件类型，但客户端必须忽略未在此字段中列出的那些。

对象种类“缓存”

cache 对象类型列出了缓存条目。这些是 CMake 语言变量 存储在构建树的持久缓存 (CMakeCache.txt) 中。

只有一个 cache 对象主要版本，版本 2。版本 1 不存在以避免与来自 cmake-server(7) 模式的混淆。

“缓存”版本 2

cache 对象版本 2 是一个 JSON 对象：

{
  "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."
        }
      ]
    }
  ]
}

特定于 cache 对象的成员是：

条目

一个 JSON 数组，其每个条目都是指定缓存条目的 JSON 对象。每个条目的成员是：

名字

指定条目名称的字符串。

价值

指定条目值的字符串。

类型

一个字符串，指定 cmake-gui(1) 用来选择要编辑的小部件的条目类型。

属性

指定相关缓存条目属性的 JSON 条目数组<缓存条目属性>`。每个条目都是一个包含成员的 JSON 对象：

名字

一个字符串，指定缓存条目属性的名称。

价值

指定缓存条目属性值的字符串。

对象种类“cmakeFiles”

cmakeFiles 对象种类列出了 CMake 在配置和生成构建系统时使用的文件。这些包括 CMakeLists.txt 文件以及包含的 .cmake 文件。

只有一个 cmakeFiles 对象主要版本，版本 1。

“cmakeFiles”版本 1

cmakeFiles 对象版本 1 是一个 JSON 对象：

{
  "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"
    }
  ]
}

特定于 cmakeFiles 对象的成员是：

路径

包含成员的 JSON 对象：

来源

一个字符串，指定顶级源目录的绝对路径，用正斜杠表示。

构建

一个字符串，指定顶级构建目录的绝对路径，用正斜杠表示。

输入

一个 JSON 数组，其每个条目都是一个 JSON 对象，指定 CMake 在配置和生成构建系统时使用的输入文件。每个条目的成员是：

路径

指定 CMake 输入文件路径的字符串，用正斜杠表示。如果文件位于顶级源目录中，则路径是相对于该目录指定的。否则路径是绝对的。

isGenerated

如果路径指定顶级构建目录下的文件并且构建是源外的，则可选成员以布尔值“true”存在。该成员在源代码构建中不可用。

是外部的

如果路径指定的文件不在顶级源目录或构建目录下，则该成员具有布尔值“true”。

isCMake

如果路径指定 CMake 安装中的文件，则可选成员以布尔值“true”存在。

对象种类“工具链”

toolchains 对象种类列出了构建期间使用的工具链的属性。这些包括语言、编译器路径、ID 和版本。

只有一个 toolchains 对象主要版本，版本 1。

“工具链”版本 1

toolchains 对象版本 1 是一个 JSON 对象：

{
  "kind": "toolchains",
  "version": { "major": 1, "minor": 0 },
  "toolchains": [
    {
      "language": "C",
      "compiler": {
        "path": "/usr/bin/cc",
        "id": "GNU",
        "version": "9.3.0",
        "implicit": {
          "includeDirectories": [
            "/usr/lib/gcc/x86_64-linux-gnu/9/include",
            "/usr/local/include",
            "/usr/include/x86_64-linux-gnu",
            "/usr/include"
          ],
          "linkDirectories": [
            "/usr/lib/gcc/x86_64-linux-gnu/9",
            "/usr/lib/x86_64-linux-gnu",
            "/usr/lib",
            "/lib/x86_64-linux-gnu",
            "/lib"
          ],
          "linkFrameworkDirectories": [],
          "linkLibraries": [ "gcc", "gcc_s", "c", "gcc", "gcc_s" ]
        }
      },
      "sourceFileExtensions": [ "c", "m" ]
    },
    {
      "language": "CXX",
      "compiler": {
        "path": "/usr/bin/c++",
        "id": "GNU",
        "version": "9.3.0",
        "implicit": {
          "includeDirectories": [
            "/usr/include/c++/9",
            "/usr/include/x86_64-linux-gnu/c++/9",
            "/usr/include/c++/9/backward",
            "/usr/lib/gcc/x86_64-linux-gnu/9/include",
            "/usr/local/include",
            "/usr/include/x86_64-linux-gnu",
            "/usr/include"
          ],
          "linkDirectories": [
            "/usr/lib/gcc/x86_64-linux-gnu/9",
            "/usr/lib/x86_64-linux-gnu",
            "/usr/lib",
            "/lib/x86_64-linux-gnu",
            "/lib"
          ],
          "linkFrameworkDirectories": [],
          "linkLibraries": [
            "stdc++", "m", "gcc_s", "gcc", "c", "gcc_s", "gcc"
          ]
        }
      },
      "sourceFileExtensions": [
        "C", "M", "c++", "cc", "cpp", "cxx", "mm", "CPP"
      ]
    }
  ]
}

特定于“工具链”对象的成员是：

工具链

一个 JSON 数组，其每个条目都是一个 JSON 对象，指定与特定语言关联的工具链。每个条目的成员是：

语言

指定工具链语言的 JSON 字符串，例如 C 或 CXX。语言名称与可以传递给 project() 命令的语言名称相同。因为 CMake 只支持每种语言的单个工具链，所以这个字段可以用作键。

编译器

包含成员的 JSON 对象：

路径

为当前语言定义 CMAKE_<LANG>_COMPILER 变量时出现的可选成员。它的值是一个包含编译器路径的 JSON 字符串。

id

为当前语言定义 CMAKE_<LANG>_COMPILER_ID 变量时出现的可选成员。它的值是一个包含编译器 ID（GNU、MSVC 等）的 JSON 字符串。

版本

为当前语言定义 CMAKE_<LANG>_COMPILER_VERSION 变量时出现的可选成员。它的值是一个包含编译器版本的 JSON 字符串。

目标

为当前语言定义 CMAKE_<LANG>_COMPILER_TARGET 变量时出现的可选成员。它的值是一个 JSON 字符串，包含编译器的交叉编译目标。

隐式

包含成员的 JSON 对象：

includeDirectories

为当前语言定义 CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES 变量时出现的可选成员。它的值是一个由 JSON 字符串组成的 JSON 数组，其中每个字符串都包含一个指向编译器隐式包含目录的路径。

链接目录

为当前语言定义 CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES 变量时出现的可选成员。它的值是一个由 JSON 字符串组成的 JSON 数组，其中每个字符串都包含一个指向编译器隐式链接目录的路径。

linkFrameworkDirectories

为当前语言定义 CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES 变量时出现的可选成员。它的值是一个由 JSON 字符串组成的 JSON 数组，其中每个字符串都包含一个指向编译器隐式链接框架目录的路径。

链接库

为当前语言定义 CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES 变量时出现的可选成员。它的值是一个由 JSON 字符串组成的 JSON 数组，其中每个字符串都包含一个指向编译器隐式链接库的路径。

sourceFileExtensions

为当前语言定义 CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS 变量时出现的可选成员。它的值是一个 JSON 字符串数组，其中每个字符串都包含该语言的文件扩展名（没有前导点）。