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 безсостоятельного запроса клиента

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, содержащему объект «каталога» «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, содержащему объект «цели» «codemodel» версии 2.

"codemodel" version 2 "directory" object

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

paths

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

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

installers

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

component

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

destination

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

paths

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

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

from

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

to

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

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

type

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

file: Вызов install(FILES) или install(PROGRAMS). Члены destination и paths заполнены, пути под корневой директорией исходных файлов выражены относительно неё. Может существовать член isOptional. Данный тип не имеет дополнительных членов.
directory: Вызов install(DIRECTORY). Члены destination и paths заполнены, пути под корневой директорией исходных файлов выражены относительно неё. Может существовать член isOptional. Данный тип не имеет дополнительных членов.
target: Вызов install(TARGETS). Члены destination и paths заполнены, пути под корневой директорией сборки выражены относительно неё. Может существовать член isOptional. Этот тип имеет дополнительные члены targetId, targetIndex, targetIsImportLibrary, и targetInstallNamelink.
export: Вызов install(EXPORT). Члены destination и paths заполнены, пути под корневой директорией сборки выражены относительно неё. Элементы 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, и установщик предназначен для файла импорта библиотеки Windows DLL или для файла импорта линковщика 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

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

language

Строка, определяющая язык (например, C, 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

Объект версии 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.

Тип объекта "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(). Поскольку CMake поддерживает только один набор инструментов на язык, это поле может быть использовано в качестве ключа.

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.22/manual/cmake-file-api.7.html