cmake-file-api(7)

Введение
API v1
Типы объектов

Введение

CMake предоставляет API на основе файлов, которое клиенты могут использовать для получения семантической информации о системах сборки, сгенерированных CMake. Клиенты могут использовать API, записывая файлы запросов в определённое место в дереве сборки, чтобы запросить ноль или более типов объектов. При генерации CMake системы сборки в этом дереве сборки, он будет читать файлы запросов и записывать файлы ответов для чтения клиентом.

API на основе файлов использует директорию <build>/.cmake/api/ в верхней части дерева сборки. API имеет версионирование, чтобы поддерживать изменения в структуре файлов в директории API. Версионирование структуры файлов API ортогонально версионированию типов объектов, используемых в ответах. Данная версия CMake поддерживает только одну версию API, API v1.

API v1

API v1 хранится в директории <build>/.cmake/api/v1/. Она имеет следующие поддиректории:

query/

Содержит файлы запросов, написанные клиентами. Они могут быть v1 общими бессостоятельными файлами запросов, v1 бессостоятельными файлами запросов клиента или v1 состоятельными файлами запросов клиента.

reply/

Содержит файлы ответов, записываемые CMake при каждом запуске для генерации системы сборки. Они индексируются файлом v1 файла индекса ответов, который может ссылаться на дополнительные v1 файлы ответов. Все файлы ответов принадлежат CMake. Клиенты никогда не должны их удалять.

Клиенты могут в любое время искать и читать файл индекса ответов. Клиенты могут по желанию создать директорию reply/ в любое время и отслеживать её появление для нового файла индекса ответов.

v1 Общие бессостоятельные файлы запросов

Общие бессостоятельные файлы запросов позволяют клиентам совместно запрашивать основные версии типов объектов и получить все распознанные версии CMake, которое запущено.

Клиенты могут создавать общие запросы, создавая пустые файлы в директории v1/query/. Формат:

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

где <kind> — один из типов объектов, -v — литерал, и <major> — номер основной версии.

Файлы этого формата представляют собой бессостоятельные общие запросы, не принадлежащие ни одному конкретному клиенту. После создания их не следует удалять без внешней координации клиента или вмешательства человека.

v1 Бессостоятельные файлы запросов клиента

Бессостоятельные файлы запросов клиента позволяют клиентам создавать собственные запросы на основные версии типов объектов и получать все распознанные версии CMake, которое запущено.

Клиенты могут создавать собственные запросы, создавая пустые файлы в поддиректориях запросов, специфичных для клиента. Формат:

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

где client- — литерал, <client> — строка, уникально идентифицирующая клиента, <kind> — один из типов объектов, -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": {}
}

Члены:

requests

JSON-массив, содержащий ноль или более запросов. Каждый запрос — JSON-объект с членами:

kind

Указывает один из типов объектов, которые должны быть включены в ответ.

version

Указывает версию(и) типа объекта, которую клиент понимает. Версии имеют основные и второстепенные компоненты, следуя соглашениям семантической версии. Значение должно быть

целым JSON-числом, указывающим (неотрицательный) номер основной версии, или
JSON-объектом, содержащим major и (необязательно) minor члены, указывающие неотрицательные целые компоненты версии, или
JSON-массивом, элементы которого являются любым из вышеперечисленного.

client

Необязательный член, зарезервированный для использования клиентом. Это значение сохраняется в ответе, написанном для клиента в файле v1 индекса ответов, но в противном случае игнорируется. Клиенты могут использовать его для передачи пользовательской информации с запросом в ответ.

Для каждого запрошенного типа объекта CMake выберет первую версию, которую он распознаёт для этого типа среди тех, которые перечислены в запросе. Ответ будет использовать выбранную главную версию с наивысшей второстепенной версией, известной запущенному CMake для этой главной версии. Поэтому клиенты должны перечислять все поддерживаемые главные версии в предпочтительном порядке вместе с минимальной необходимой второстепенной версией для каждой главной версии.

client

Другие 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": {
      "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, сгенерировавшем ответ. Он содержит члены:

version

JSON-объект, определяющий версию CMake с членами:

major, minor, patch: Целочисленные значения, определяющие главную, второстепенную и исправленную версии.
suffix: Строка, определяющая суффикс версии, если таковой имеется, например g0abc3.
string: Строка, определяющая полную версию в формате <major>.<minor>.<patch>[-<suffix>].
isDirty: Логическое значение, указывающее, была ли версия построена из дерева с контролем версий с локальными изменениями.

paths

JSON-объект, определяющий пути к компонентам CMake. Он содержит члены для cmake, ctest, и cpack, значениями которых являются JSON-строки, определяющие абсолютный путь к каждому инструменту, представленному с помощью слешей. Также он содержит член root для абсолютного пути к каталогу, содержащему ресурсы CMake, такие как каталог Modules/ (см. CMAKE_ROOT).

generator

JSON-объект, описывающий используемый генератор CMake. Он содержит члены:

name: Строка, определяющая имя генератора.
platform: Если генератор поддерживает CMAKE_GENERATOR_PLATFORM, это строка, определяющая имя платформы генератора.

objects

JSON-массив, перечисляющий все версии всех видов объектов, сгенерированных в качестве части ответа. Каждый элемент массива представляет собой ссылку на файл ответа v1.

reply

JSON-объект, отражающий содержимое каталога query/, загруженного CMake для создания ответа. Члены имеют вид

<kind>-v<major>

Такой член появляется для каждого из файлов запросов v1 общего состояния, которые CMake распознал как запрос на вид объекта <kind> с основной версией <major>. Значением является ссылка на файл ответа v1 на соответствующий файл ответа для этого вида объекта и версии.

<unknown>

Такой член появляется для каждого из файлов запросов v1 общего состояния, которые CMake не распознал. Значение является JSON-объектом с одним членом error, содержащим строку с сообщением об ошибке, указывающей, что файл запроса неизвестен.

client-<client>

Такой член появляется для каждого каталога, принадлежащего клиенту, содержащего файлы запросов v1 клиента без состояния. Значение является JSON-объектом, отражающим содержимое каталога query/client-<client>/. Члены имеют вид:

<kind>-v<major>

Такой член появляется для каждого из файлов запросов v1 клиента без состояния, которые CMake распознал как запрос на вид объекта <kind> с основной версией <major>. Значением является ссылка на файл ответа v1 на соответствующий файл ответа для этого вида объекта и версии.

<unknown>

Такой член появляется для каждого из файлов запросов v1 клиента без состояния, которые CMake не распознал. Значение является JSON-объектом с единственным членом error, содержащим строку с сообщением об ошибке, указывающей, что файл запроса неизвестен.

query.json

Этот член появляется для клиентов, использующих файлы запросов v1 клиента со состоянием. Если файл query.json не удалось прочитать или разобрать как JSON-объект, этот член является JSON-объектом с одним членом error, содержащим строку с сообщением об ошибке. В противном случае этот член является JSON-объектом, отражающим содержимое файла query.json. Члены:

client

Копия файла query.json член client, если он существует.

requests

Копия файла query.json член requests, если он существует.

responses

Если член query.json файла requests отсутствует или недействителен, этот член является JSON-объектом с одним членом error, содержащим строку с сообщением об ошибке. В противном случае этот член содержит JSON-массив с ответом для каждого элемента массива requests, в том же порядке. Каждый ответ является

JSON-объектом с единственным членом error, содержащим строку с сообщением об ошибке, или
ссылкой на файл ответа v1 на соответствующий файл ответа для запрошенного типа объекта и выбранной версии.

После чтения файла индекса ответа клиенты могут прочитать другие файлы ответов v1, на которые он ссылается.

Ссылка на файл ответа v1

Файл индекса ответа представляет каждую ссылку на другой файл ответа с помощью JSON-объекта с членами:

kind: Строка, определяющая один из видов объектов.
version: JSON-объект с членами major и minor, определяющими целочисленные компоненты версии типа объекта.
jsonFile: JSON-строка, определяющая путь относительно файла индекса ответа к другому JSON-файлу, содержащему объект.

Файлы ответов v1

Файлы ответов, содержащие конкретные типы объектов, записываются CMake. Имена этих файлов не определены и не должны интерпретироваться клиентами. Клиенты должны сначала прочитать файл индекса ответов v1 и следовать ссылкам на имена нужных объектов ответа.

Файлы ответов (включая файл индекса) никогда не будут заменены файлами с тем же именем, но с другим содержимым. Это позволяет клиенту одновременно считывать файлы с работающим CMake, который может сгенерировать новый ответ. Однако после генерации нового ответа CMake попытается удалить файлы ответов из предыдущих запусков, которые он не только что записал. Если клиент пытается прочитать файл ответа, на который ссылается индекс, но находит файл отсутствующим, это означает, что параллельный CMake сгенерировал новый ответ. Клиент может просто начать заново, прочитав новый файл индекса ответа.

Типы объектов

API CMake на основе файлов сообщает семантическую информацию о системе построения, используя следующие типы JSON-объектов. Каждый тип объекта независимо версионируется, используя семантическое версионирование с главными и второстепенными компонентами. Каждый тип объекта имеет форму:

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

Член kind представляет собой строку, определяющую имя типа объекта. Член version представляет собой JSON-объект с членами major и minor, определяющими целочисленные компоненты версии типа объекта. Дополнительные члены верхнего уровня специфичны для каждого типа объекта.

Тип объекта «codemodel»

Тип объекта codemodel описывает структуру системы построения, как она моделируется CMake.

Существует только одна основная версия типа объекта codemodel, версия 2. Версия 1 не существует, чтобы избежать путаницы с версией из режима cmake-server(7).

“codemodel” версия 2

Объект codemodel версии 2 представляет собой JSON-объект:

{
  "kind": "codemodel",
  "version": { "major": 2, "minor": 0 },
  "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>"
        }
      ]
    }
  ]
}

Члены, специфичные для объектов codemodel, это:

paths

Объект JSON, содержащий члены:

source: Строка, определяющая абсолютный путь к директории исходного кода верхнего уровня, представленная с помощью слешей.
build: Строка, определяющая абсолютный путь к директории сборки верхнего уровня, представленная с помощью слешей.

configurations

Массив JSON записей, соответствующих доступным конфигурациям сборки. В генераторах с одной конфигурацией есть одна запись для значения переменной CMAKE_BUILD_TYPE. В генераторах с несколькими конфигурациями есть запись для каждой конфигурации, указанной в переменной CMAKE_CONFIGURATION_TYPES. Каждая запись — это объект JSON, содержащий члены:

name

Строка, определяющая имя конфигурации, например Debug.

directories

Массив JSON записей, каждая из которых соответствует директории системы сборки, директория исходного кода которой содержит файл CMakeLists.txt. Первая запись соответствует директории верхнего уровня. Каждая запись — это объект JSON, содержащий члены:

source

Строка, определяющая путь к директории исходного кода, представленная с помощью слешей. Если директория находится внутри директории исходного кода верхнего уровня, путь указывается относительно этой директории (с . для самой директории исходного кода верхнего уровня). В противном случае путь является абсолютным.

build

Строка, определяющая путь к директории сборки, представленная с помощью слешей. Если директория находится внутри директории сборки верхнего уровня, путь указывается относительно этой директории (с . для самой директории сборки верхнего уровня). В противном случае путь является абсолютным.

parentIndex

Необязательный член, присутствующий, когда директория не является директорией верхнего уровня. Значение — это 0-основанный индекс целого без знака другого элемента в главном массиве directories, соответствующем родительской директории, которая добавила эту директорию в качестве поддиректории.

childIndexes

Необязательный член, присутствующий, когда у директории есть поддиректории. Значение — массив JSON записей, соответствующих поддиректориям, созданным командами add_subdirectory() или subdirs(). Каждая запись — это 0-основанный индекс целого без знака другого элемента в главном массиве directories.

projectIndex

Целое без знака, 0-основанный индекс в главном массиве projects, указывающий на проект системы сборки, к которому принадлежит эта директория.

targetIndexes

Необязательный член, присутствующий, когда у самой директории есть цели, за исключением тех, которые принадлежат поддиректориям. Значение — массив JSON записей, соответствующих целям. Каждая запись — это 0-основанный индекс целого без знака в главном массиве targets.

minimumCMakeVersion

Необязательный член, присутствующий, когда известна минимальная требуемая версия CMake для директории. Это версия <min>, заданная самому локальному вызову команды cmake_minimum_required(VERSION) в самой директории или в одном из её предков. Значение — это объект JSON с одним членом:

string

Строка, определяющая минимальную требуемую версию в формате:

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

Каждый компонент — целое без знака, а суффикс может быть произвольной строкой.

hasInstallRule

Необязательный член, присутствующий со значением типа булево true, когда директория или одна из её поддиректорий содержит какие-либо правила install(), т.е. доступно ли правило make install или эквивалентное.

projects

Массив JSON записей, соответствующих проекту верхнего уровня и подпроектам, определённым в системе сборки. Каждый (под-)проект соответствует директории исходного кода, в файле которой CMakeLists.txt команда project() вызывается с именем проекта, отличным от имени родительской директории. Первая запись соответствует проекту верхнего уровня.

Каждая запись — это объект JSON, содержащий члены:

name: Строка, определяющая имя, заданное команде project().
parentIndex: Необязательный член, присутствующий, когда проект не является проектом верхнего уровня. Значение — 0-основанный индекс целого без знака другого элемента в главном массиве projects, соответствующем родительскому проекту, который добавил этот проект в качестве подпроекта.
childIndexes: Необязательный член, присутствующий, когда у проекта есть подпроекты. Значение — массив JSON записей, соответствующих подпроектам. Каждая запись — 0-основанный индекс целого без знака другого элемента в главном массиве projects.
directoryIndexes: Массив JSON записей, соответствующих директориям системы сборки, которые являются частью проекта. Первая запись соответствует директории верхнего уровня проекта. Каждая запись — 0-основанный индекс целого без знака в главном массиве directories.
targetIndexes: Необязательный член, присутствующий, когда у проекта есть цели, за исключением тех, которые принадлежат подпроектам. Значение — массив JSON записей, соответствующих целям. Каждая запись — 0-основанный индекс целого без знака в главном массиве targets.

targets

Массив JSON записей, соответствующих целям системы сборки. Такие цели создаются вызовами add_executable(), add_library() и add_custom_target(), исключая импортированные цели и интерфейсные библиотеки (которые не генерируют никаких правил сборки). Каждая запись — это объект JSON, содержащий члены:

name: Строка, определяющая имя цели.
id: Строка, уникально идентифицирующая цель. Соответствует полю id в файле, на который ссылается jsonFile.
directoryIndex: Целое без знака, 0-основанный индекс в главном массиве directories системы сборки, в котором определена цель.
projectIndex: Целое без знака, 0-основанный индекс в главном массиве projects системы сборки, в котором определена цель.
jsonFile: Строка JSON, определяющая путь, относительный к файлу codemodel, к другому файлу JSON, содержащему объект «target» «codemodel» версии 2.

“codemodel” version 2 “target” object

Объект «target» codemodel версии 2 используется в массиве targets объекта «codemodel» версии 2. Каждый объект «target» — это объект JSON с членами:

name

Строка, определяющая логическое имя целевого объекта.

id

Строка, уникально идентифицирующая целевой объект. Формат не определён и не должен интерпретироваться клиентами.

type

Строка, определяющая тип целевого объекта. Значение должно быть одним из EXECUTABLE, STATIC_LIBRARY, SHARED_LIBRARY, MODULE_LIBRARY, OBJECT_LIBRARY, или UTILITY.

backtrace

Необязательный член, присутствующий, когда доступен отладочный след CMake до команды в исходном коде, создавшей целевой объект. Значение — целое без знака, 0-основанный индекс в массиве члена backtraceGraph по имени nodes.

folder

Необязательный член, присутствующий, когда свойство целевого объекта FOLDER задано. Значение — JSON-объект с одним членом:

name: Строка, определяющая имя папки целевого объекта.

paths

JSON-объект, содержащий члены:

source: Строка, определяющая путь к каталогу исходных файлов целевого объекта, представленный с помощью слешей. Если каталог находится внутри корневого каталога исходных файлов, путь указывается относительно этого каталога (с . для самого корневого каталога исходных файлов). В противном случае путь является абсолютным.
build: Строка, определяющая путь к каталогу сборки целевого объекта, представленный с помощью слешей. Если каталог находится внутри корневого каталога сборки, путь указывается относительно этого каталога (с . для самого корневого каталога сборки). В противном случае путь является абсолютным.

nameOnDisk

Необязательный член, присутствующий для целевых объектов типа исполняемый файл и библиотека, скомпонованы или архивированы в один основной артефакт. Значение — строка, определяющая имя файла этого артефакта на диске.

artifacts

Необязательный член, присутствующий для целевых объектов типа исполняемый файл и библиотека, которые производят артефакты на диске, предназначенные для использования зависимостями. Значение — JSON-массив записей, соответствующих артефактам. Каждая запись — JSON-объект, содержащий один член:

path: Строка, определяющая путь к файлу на диске, представленный с помощью слешей. Если файл находится внутри корневого каталога сборки, путь указывается относительно этого каталога. В противном случае путь является абсолютным.

isGeneratorProvided

Необязательный член, присутствующий с булевым значением true, если целевой объект предоставлен генератором системы сборки CMake, а не командой в исходном коде.

install

Необязательный член, присутствующий, когда целевой объект имеет правило install(). Значение — JSON-объект с членами:

prefix

JSON-объект, определяющий префикс установки. Он имеет один член:

path: Строка, определяющая значение CMAKE_INSTALL_PREFIX.

destinations

JSON-массив записей, определяющих путь назначения установки. Каждая запись — JSON-объект с членами:

path: Строка, определяющая путь назначения установки. Путь может быть абсолютным или относительным к префиксу установки.
backtrace: Необязательный член, присутствующий, когда доступен отладочный след CMake до вызова команды install(), указавшей этот путь назначения. Значение — целое без знака, 0-основанный индекс в массиве члена backtraceGraph по имени nodes.

link

Необязательный член, присутствующий для целевых объектов типа исполняемый файл и динамическая библиотека, которые скомпонованы в исполняемый файл во время работы. Значение — JSON-объект с членами, описывающими этап компоновки:

language

Строка, определяющая язык (например, C, CXX, Fortran) используемой цепочки инструментов для вызова компоновщика.

commandFragments

Необязательный член, присутствующий, когда доступны фрагменты командной строки вызова компоновщика. Значение — JSON-массив записей, определяющих упорядоченные фрагменты. Каждая запись — JSON-объект с членами:

fragment

Строка, определяющая фрагмент командной строки вызова компоновщика. Значение закодировано в формате командной строки собственной оболочки системы сборки.

role

Строка, определяющая роль содержимого фрагмента:

flags: флаги компоновки.
libraries: пути к файлам библиотек или флаги компоновки библиотек.
libraryPath: флаги путей поиска библиотек.
frameworkPath: флаги путей поиска macOS-фреймворков.

lto

Необязательный член, присутствующий с булевым значением true, когда включено оптимизация при компоновке (также известная как межпроцедурная оптимизация или генерация кода во время компоновки).

sysroot

Необязательный член, присутствующий, когда определены переменные CMAKE_SYSROOT_LINK или CMAKE_SYSROOT. Значение — JSON-объект с одним членом:

path: Строка, определяющая абсолютный путь к корневому каталогу, представленный с помощью слешей.

archive

Необязательный член, присутствующий для целевых объектов типа статическая библиотека. Значение — JSON-объект с членами, описывающими этап архивации:

commandFragments

Необязательный член, присутствующий, когда доступны фрагменты командной строки вызова архиватора. Значение — JSON-массив записей, определяющих фрагменты. Каждая запись — JSON-объект с членами:

fragment

Строка, определяющая фрагмент командной строки вызова архиватора. Значение закодировано в формате командной строки собственной оболочки системы сборки.

role

Строка, определяющая роль содержимого фрагмента:

flags: флаги архиватора.

lto

Необязательный член, присутствующий с булевым значением true, когда включена оптимизация при компоновке (также известная как межпроцедурная оптимизация или генерация кода во время компоновки).

dependencies

Необязательный член, присутствующий, когда целевой объект зависит от других целевых объектов. Значение — JSON-массив записей, соответствующих зависимостям. Каждая запись — JSON-объект с членами:

id: Строка, уникально идентифицирующая целевой объект, от которого зависит этот целевой объект. Совпадает с главным членом id другого целевого объекта.
backtrace: Необязательный член, присутствующий, когда доступен отладочный след CMake до вызова команды add_dependencies(), target_link_libraries() или другой команды, создавшей эту зависимость. Значение — целое без знака, 0-основанный индекс в массиве члена backtraceGraph по имени nodes.

sources

JSON-массив записей, соответствующих исходным файлам целевого объекта. Каждая запись — JSON-объект с членами:

path: Строка, определяющая путь к исходному файлу на диске, представленный с помощью слешей. Если файл находится внутри корневого каталога исходных файлов, путь указывается относительно этого каталога. В противном случае путь является абсолютным.
compileGroupIndex: Необязательный член, присутствующий, когда исходный файл компилируется. Значение — целое без знака, 0-основанный индекс в массиве compileGroups.
sourceGroupIndex: Необязательный член, присутствующий, когда исходный файл является частью группы исходных файлов, либо через команду source_group(), либо по умолчанию. Значение — целое без знака, 0-основанный индекс в массиве sourceGroups.
isGenerated: Необязательный член, присутствующий с булевым значением true, если исходный файл является GENERATED.
backtrace: Необязательный член, присутствующий, когда доступен отладочный след CMake до вызова команды target_sources(), add_executable(), add_library(), add_custom_target() или другой команды, добавившей этот исходный файл в целевой объект. Значение — целое без знака, 0-основанный индекс в массиве члена backtraceGraph по имени nodes.

sourceGroups

Дополнительный член, присутствующий, когда исходные файлы сгруппированы командой source_group() или по умолчанию. Значение представляет собой JSON-массив записей, соответствующих группам. Каждая запись — JSON-объект с членами:

name: Строка, определяющая имя группы исходных файлов.
sourceIndexes: JSON-массив, перечисляющий исходные файлы, принадлежащие группе. Каждая запись — целое беззнаковое число, 0-основанный индекс в главном sources массиве для целевого объекта.

compileGroups

Дополнительный член, присутствующий, когда целевой объект имеет исходные файлы, которые компилируются. Значение — JSON-массив записей, соответствующих группам исходных файлов, которые все компилируются с одинаковыми настройками. Каждая запись — JSON-объект с членами:

sourceIndexes

JSON-массив, перечисляющий исходные файлы, принадлежащие группе. Каждая запись — целое беззнаковое число, 0-основанный индекс в главном sources массиве для целевого объекта.

language

Строка, определяющая язык (например, C, CXX, Fortran) компилятора, используемого для компиляции исходного файла.

compileCommandFragments

Дополнительный член, присутствующий, когда доступны фрагменты вызова компилятора. Значение — JSON-массив, содержащий упорядоченные фрагменты. Каждая запись — JSON-объект с одним членом:

fragment: Строка, определяющая фрагмент вызова компилятора. Значение закодировано в формате оболочки системы сборки.

includes

Дополнительный член, присутствующий, когда есть каталоги включения. Значение — JSON-массив с записью для каждого каталога. Каждая запись — JSON-объект с членами:

path: Строка, определяющая путь к каталогу включения, представленный с помощью слэшей.
isSystem: Дополнительный член, присутствующий со значением булевого типа true, если каталог включения помечен как системный каталог включения.
backtrace: Дополнительный член, присутствующий, когда доступна трассировка CMake языка к вызову target_include_directories() или другой команде, которая добавила этот каталог включения. Значение — целое беззнаковое число, 0-основанный индекс в массиве backtraceGraph члена nodes.

defines

Дополнительный член, присутствующий, когда есть определения препроцессора. Значение — JSON-массив с записью для каждого определения. Каждая запись — JSON-объект с членами:

define: Строка, определяющая определение препроцессора в формате <name>[=<value>], например, DEF или DEF=1.
backtrace: Дополнительный член, присутствующий, когда доступна трассировка CMake языка к вызову target_compile_definitions() или другой команде, которая добавила это определение препроцессора. Значение — целое беззнаковое число, 0-основанный индекс в массиве backtraceGraph члена nodes.

sysroot

Дополнительный член, присутствующий, когда переменная CMAKE_SYSROOT_COMPILE или CMAKE_SYSROOT определена. Значение — JSON-объект с одним членом:

path: Строка, определяющая абсолютный путь к sysroot, представленный с помощью слэшей.

backtraceGraph

JSON-объект, описывающий график трассировок, узлы которых ссылаются на члены backtrace в других местах. Члены:

nodes

JSON-массив, перечисляющий узлы в графе трассировки. Каждая запись — JSON-объект с членами:

file: Целое беззнаковое число, 0-основанный индекс в массиве трассировки files.
line: Дополнительный член, присутствующий, когда узел представляет строку в файле. Значение — целое беззнаковое число, номер строки (1-основанный).
command: Дополнительный член, присутствующий, когда узел представляет вызов команды в файле. Значение — целое беззнаковое число, 0-основанный индекс в массиве трассировки commands.
parent: Дополнительный член, присутствующий, когда узел не является нижней частью стека вызовов. Значение — целое беззнаковое число, 0-основанный индекс другой записи в массиве трассировки nodes.

commands

JSON-массив, перечисляющий имена команд, на которые ссылаются узлы трассировки. Каждая запись — строка, определяющая имя команды.

files

JSON-массив, перечисляющий файлы CMake языка, на которые ссылаются узлы трассировки. Каждая запись — строка, определяющая путь к файлу, представленный с помощью слэшей. Если файл находится в каталоге верхнего уровня исходных файлов, путь указывается относительно этого каталога. В противном случае путь абсолютный.

Тип объекта “cache”

Объект типа cache перечисляет записи кэша. Это Переменные, хранящиеся в постоянном кэше (CMakeCache.txt) для дерева сборки.

Существует только один основной номер версии объекта cache, версия 2. Версии 1 не существует, чтобы избежать путаницы с версией из режима cmake-server(7).

“cache” версия 2

Объект версии 2 типа cache представляет собой 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:

entries

JSON-массив, записи которого представляют собой JSON-объекты, определяющие запись кэша. Члены каждой записи:

name

Строка, определяющая имя записи.

value

Строка, определяющая значение записи.

type

Строка, определяющая тип записи, используемая cmake-gui(1) для выбора виджета редактирования.

properties

JSON-массив записей, определяющих связанные свойства записей кэша. Каждая запись — JSON-объект, содержащий члены:

name: Строка, определяющая имя свойства записи кэша.
value: Строка, определяющая значение свойства записи кэша.

Тип объекта “cmakeFiles”

Объект типа cmakeFiles перечисляет файлы, используемые CMake при конфигурировании и генерации системы сборки. Это включают файлы CMakeLists.txt, а также включенные файлы .cmake.

Существует только один основной номер версии объекта cmakeFiles, версия 1.

“cmakeFiles” версия 1

Объект версии 1 типа cmakeFiles представляет собой 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:

paths

JSON-объект, содержащий члены:

source: Строка, определяющая абсолютный путь к каталогу верхнего уровня исходных файлов, представленный с помощью слэшей.
build: Строка, определяющая абсолютный путь к каталогу верхнего уровня сборки, представленный с помощью слэшей.

inputs

JSON-массив, записи которого представляют собой JSON-объекты, определяющие входной файл, используемый CMake при конфигурировании и генерации системы сборки. Члены каждой записи:

path: Строка, определяющая путь к входному файлу CMake, представленный с помощью слэшей. Если файл находится в каталоге верхнего уровня исходных файлов, путь указывается относительно этого каталога. В противном случае путь абсолютный.
isGenerated: Дополнительный член, присутствующий со значением булевого типа true, если путь указывает на файл, находящийся в каталоге верхнего уровня сборки, и сборка выполняется вне исходного каталога. Этот член недоступен при сборке в исходном каталоге.
isExternal: Дополнительный член, присутствующий со значением булевого типа true, если путь указывает на файл, который не находится в каталогах верхнего уровня исходных или сборки.
isCMake: Дополнительный член, присутствующий со значением булевого типа true, если путь указывает на файл в установке CMake.

© 2000–2020 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.16/manual/cmake-file-api.7.html