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

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. Он имеет члены:

multiConfig: Булево значение, определяющее, поддерживает ли генератор несколько конфигураций выходных данных.
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

Объект версии 2 codemodel — это объект JSON:

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

paths

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

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

configurations

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

name

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

directories

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

source

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

build

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

parentIndex

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

childIndexes

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

projectIndex

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

targetIndexes

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

minimumCMakeVersion

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

string

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

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

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

hasInstallRule

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

jsonFile

Строка JSON, определяющая путь относительно файла codemodel к другому файлу JSON, содержащему объект «directory» «codemodel» версии 2.

Этот поле был добавлен в версии codemodel 2.3.

projects

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

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

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

targets

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

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

Объект «directory» «codemodel» версии 2

Объект «directory» codemodel ссылается на массив directories объекта "codemodel" версии 2. Каждый объект «directory» — это объект JSON с членами:

paths

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

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

installers

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

component

Строка, определяющая компонент, выбранный вызовом соответствующей команды install().

destination

Необязательный член, присутствующий для определённых значений type ниже. Значение — строка, определяющая путь назначения установки. Путь может быть абсолютным или относительным к префиксу установки.

paths

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

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

from

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

to

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

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

type

Строка, определяющая тип правила установки. Значение — одно из следующих, некоторые варианты предоставляют дополнительные члены:

file: Вызов install(FILES) или install(PROGRAMS). Члены destination и paths заполнены, пути внутри каталога верхнего уровня source выражены относительно него. Член isOptional может существовать. Этот тип не имеет дополнительных членов.
directory: Вызов install(DIRECTORY). Члены destination и paths заполнены, пути внутри каталога верхнего уровня source выражены относительно него. Член isOptional может существовать. Этот тип не имеет дополнительных членов.
target: Вызов install(TARGETS). Члены destination и paths заполнены, пути внутри каталога верхнего уровня build выражены относительно него. Член isOptional может существовать. Этот тип имеет дополнительные члены targetId, targetIndex, targetIsImportLibrary, и targetInstallNamelink.
export: Вызов install(EXPORT). Члены destination и paths заполнены, пути внутри каталога верхнего уровня build выражены относительно него. Записи paths относятся к файлам, сгенерированным CMake для установки, и их фактические значения считаются частными реализационными подробностями. Этот тип имеет дополнительные члены exportName и exportTargets.
script: Вызов install(SCRIPT). Этот тип имеет дополнительный член scriptFile.
code: Вызов install(CODE). Этот тип не имеет дополнительных членов.
importedRuntimeArtifacts: Вызов install(IMPORTED_RUNTIME_ARTIFACTS). Член destination заполнен. Член isOptional может существовать. Этот тип не имеет дополнительных членов.
runtimeDependencySet: Вызов install(RUNTIME_DEPENDENCY_SET) или вызов install(TARGETS) с RUNTIME_DEPENDENCIES. Член destination заполнен. Этот тип имеет дополнительные члены runtimeDependencySetName и runtimeDependencySetType.

isExcludeFromAll

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

isForAllComponents

Необязательный член, присутствующий со значением true булевого типа при вызове install(SCRIPT|CODE) с опцией ALL_COMPONENTS.

isOptional

Необязательный член, присутствующий со значением true булевого типа при вызове install() с опцией OPTIONAL . Это разрешено, когда type равно file, directory, или target.

targetId

Необязательный член, присутствующий, когда type равно target . Значение — уникальный идентификатор целевого объекта для установки. Соответствует члену id целевого объекта в массиве targets основного объекта "codemodel".

targetIndex

Необязательный член, присутствующий, когда type равно target . Значение — целое число без знака, 0-основанный индекс в массиве targets основного объекта "codemodel" для целевого объекта для установки.

targetIsImportLibrary

Необязательный член, присутствующий, когда type равно target, и установщик предназначен для файла библиотеки импорта DLL Windows или для файла импорта компоновщика AIX. Если присутствует, имеет булевое значение true.

targetInstallNamelink

Необязательный член, присутствующий, когда type равно target и установщик соответствует целевому объекту, который может использовать символические ссылки для реализации свойств целевого объекта VERSION и SOVERSION. Значение — строка, указывающая, как установщик должен обрабатывать символические ссылки: skip означает, что установщик должен пропустить символические ссылки и установить только реальный файл, а only означает, что установщик должен установить только символические ссылки и не устанавливать реальный файл. Во всех случаях член paths перечисляет то, что фактически устанавливается.

exportName

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

exportTargets

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

id: Строка, уникально идентифицирующая целевой объект. Соответствует члену id целевого объекта в массиве targets основного объекта "codemodel".
index: Целое число без знака, 0-основанный индекс в массиве targets основного объекта "codemodel" для целевого объекта.

runtimeDependencySetName

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

runtimeDependencySetType

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

library: Указывает, что этот установщик устанавливает зависимости, которые не являются macOS-фреймворками.
framework: Указывает, что этот установщик устанавливает зависимости, которые являются macOS-фреймворками.

scriptFile

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

backtrace

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

backtraceGraph

A "codemodel" version 2 "backtrace graph" whose nodes are referenced from backtrace members elsewhere in this "directory" object.

"codemodel" version 2 "target" object

A "codemodel" version 2 "target" object is referenced by a "codemodel" version 2 object's targets array. Each "target" object is a JSON object with members:

name

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

id

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

type

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

backtrace

Необязательный член, присутствующий, когда доступен трассировка CMake языка к команде в исходном коде, которая создала целевой объект. Значение — это беззнаковое целое число, индекс с нуля в массиве 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(), которая указала это место назначения. Значение — это беззнаковое целое число, индекс с нуля в массиве 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: Строка, определяющая абсолютный путь к sysroot, представленный с помощью слешей.

archive

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

commandFragments

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

fragment

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

role

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

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

lto

dependencies

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

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

sources

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

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

sourceGroups

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

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

compileGroups

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

sourceIndexes

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

language

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

languageStandard

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

backtraces: Дополнительный член, присутствующий, когда доступен обратный след CMake для настройки <LANG>_STANDARD. Если стандарт языка был установлен неявно функциями компиляции, используются эти обратные следы. Возможно, несколько функций компиляции потребуют одного и того же стандарта языка, поэтому может быть несколько обратных следов. Значение — массив JSON, где каждый элемент — целочисленная беззнаковая индекс 0-базисного массива backtraceGraph члена nodes.
standard: Строка, представляющая стандарт языка.

Этот член был добавлен в версии codemodel 2.2.

compileCommandFragments

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

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

includes

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

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

precompileHeaders

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

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

Этот член был добавлен в версии codemodel 2.1.

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

Объект "codemodel" версия 2 "граф обратных следов", чьи узлы ссылаются из backtrace членов в данном объекте "target".

"codemodel" версия 2 "граф обратных следов"

Член backtraceGraph объекта "codemodel" версия 2 "каталог" объекта или "codemodel" версия 2 "целевой объект" — 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

Объект 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, следующие:

paths

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

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

inputs

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

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

Тип объекта "toolchains"

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

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

"toolchains" версия 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"
      ]
    }
  ]
}

Члены, специфичные для объектов toolchains, следующие:

toolchains

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

language

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

compiler

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

path

Необязательный член, присутствующий при определении переменной CMAKE_<LANG>_COMPILER для текущего языка. Его значение — JSON-строка, содержащая путь к компилятору.

id

Необязательный член, присутствующий при определении переменной CMAKE_<LANG>_COMPILER_ID для текущего языка. Его значение — JSON-строка, содержащая идентификатор (GNU, MSVC и т. д.) компилятора.

version

Необязательный член, присутствующий при определении переменной CMAKE_<LANG>_COMPILER_VERSION для текущего языка. Его значение — JSON-строка, содержащая версию компилятора.

target

Необязательный член, присутствующий при определении переменной CMAKE_<LANG>_COMPILER_TARGET для текущего языка. Его значение — JSON-строка, содержащая целевой кросс-компиляции компилятора.

implicit

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

includeDirectories: Необязательный член, присутствующий при определении переменной CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES для текущего языка. Его значение — JSON-массив JSON-строк, где каждая строка содержит путь к неявной директории включения для компилятора.
linkDirectories: Необязательный член, присутствующий при определении переменной CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES для текущего языка. Его значение — JSON-массив JSON-строк, где каждая строка содержит путь к неявной директории линковки для компилятора.
linkFrameworkDirectories: Необязательный член, присутствующий при определении переменной CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES для текущего языка. Его значение — JSON-массив JSON-строк, где каждая строка содержит путь к неявной директории линковки фреймворков для компилятора.
linkLibraries: Необязательный член, присутствующий при определении переменной CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES для текущего языка. Его значение — JSON-массив JSON-строк, где каждая строка содержит путь к неявной библиотеке линковки для компилятора.

sourceFileExtensions

Необязательный член, присутствующий при определении переменной CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS для текущего языка. Его значение — JSON-массив JSON-строк, где каждая строка содержит расширение файла (без ведущей точки) для языка.

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