Spec-Zone.ru › CMake 3.20

cmake-file-api(7)

  • Введение

  • API v1

    • v1 Общие бессостоятельные запросы к файлам
    • v1 Бессостоятельные запросы к файлам клиента
    • v1 Состоятельные запросы к файлам клиента

    • v1 Файл индекса ответов

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

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

    • Тип объекта "codemodel"

      • Версия "codemodel" 2
      • Объект "target" версии "codemodel" 2

    • Тип объекта "cache"

      • Версия "cache" 2

    • Тип объекта "cmakeFiles"

      • Версия "cmakeFiles" 1

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

      • Версия "toolchains" 1

Введение

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

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

Другие query.json верхнего уровня члены зарезервированы для будущего использования. Если они присутствуют, они игнорируются для обратной совместимости.

v1 Файл индекса ответов

CMake записывает файл index-*.json в каталог v1/reply/ при каждом выполнении для генерации системы сборки. Клиенты должны сначала прочитать файл индекса ответов и могут читать другие v1 Файлы ответов только следуя ссылкам. Формат имени файла индекса ответов:

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

где index- — литерал, а <unspecified> — неопределённое имя, выбранное CMake. Всякий раз, когда генерируется новый файл индекса, ему даётся новое имя, а старое удаляется. В короткий период между этими шагами могут присутствовать несколько файлов индексов; файл индекса с наибольшим именем в лексикографическом порядке — это текущий файл индекса.

Файл индекса ответов содержит JSON-объект:

{
  "cmake": {
    "version": {
      "major": 3, "minor": 14, "patch": 0, "suffix": "",
      "string": "3.14.0", "isDirty": false
    },
    "paths": {
      "cmake": "/prefix/bin/cmake",
      "ctest": "/prefix/bin/ctest",
      "cpack": "/prefix/bin/cpack",
      "root": "/prefix/share/cmake-3.14"
    },
    "generator": {
      "multiConfig": false,
      "name": "Unix Makefiles"
    }
  },
  "objects": [
    { "kind": "<kind>",
      "version": { "major": 1, "minor": 0 },
      "jsonFile": "<file>" },
    { "...": "..." }
  ],
  "reply": {
    "<kind>-v<major>": { "kind": "<kind>",
                         "version": { "major": 1, "minor": 0 },
                         "jsonFile": "<file>" },
    "<unknown>": { "error": "unknown query file" },
    "...": {},
    "client-<client>": {
      "<kind>-v<major>": { "kind": "<kind>",
                           "version": { "major": 1, "minor": 0 },
                           "jsonFile": "<file>" },
      "<unknown>": { "error": "unknown query file" },
      "...": {},
      "query.json": {
        "requests": [ {}, {}, {} ],
        "responses": [
          { "kind": "<kind>",
            "version": { "major": 1, "minor": 0 },
            "jsonFile": "<file>" },
          { "error": "unknown query file" },
          { "...": {} }
        ],
        "client": {}
      }
    }
  }
}

Члены:

cmake

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

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"
          }
        },
        {
          "source": "sub",
          "build": "sub",
          "parentIndex": 0,
          "projectIndex": 0,
          "targetIndexes": [ 1 ],
          "minimumCMakeVersion": {
            "string": "3.14"
          }
        }
      ],
      "projects": [
        {
          "name": "MyProject",
          "directoryIndexes": [ 0, 1 ],
          "targetIndexes": [ 0, 1 ]
        }
      ],
      "targets": [
        {
          "name": "MyExecutable",
          "directoryIndex": 0,
          "projectIndex": 0,
          "jsonFile": "<file>"
        },
        {
          "name": "MyLibrary",
          "directoryIndex": 1,
          "projectIndex": 0,
          "jsonFile": "<file>"
        }
      ]
    }
  ]
}

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

paths

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

source

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

build

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

configurations

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

name

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

directories

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

source

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

build

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

parentIndex

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

childIndexes

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

projectIndex

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

targetIndexes

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

minimumCMakeVersion

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

string

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

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

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

hasInstallRule

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

projects

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

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

name

Строка, определяющая имя, заданное командой project().

parentIndex

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

childIndexes

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

directoryIndexes

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

targetIndexes

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

targets

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

name

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

id

Строка, уникально идентифицирующая целевой объект. Это соответствует полю id в файле, на который ссылается jsonFile.

directoryIndex

Целое без знака, 0-основанный индекс в главном массиве directories, указывающий на каталог системы сборки, в котором определён целевой объект.

projectIndex

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

jsonFile

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

"codemodel" версии 2 "target" объект

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

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

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

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

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

Объект версии 1 toolchains представляет собой объект 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.20/manual/cmake-file-api.7.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API