cmake-server(7)

Введение
Работа
Отладка
Протокол API

Устарело начиная с версии 3.15: Это будет удалено в будущей версии CMake. Клиенты должны использовать cmake-file-api(7) вместо него.

Введение

cmake(1) способен предоставлять семантическую информацию о коде CMake, который он выполняет, чтобы сгенерировать систему сборки. Если он запущен с параметрами командной строки -E server, он запускается в режиме длительной работы и позволяет клиенту запрашивать доступную информацию через протокол JSON.

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

Один cmake-buildsystem(7) может описывать содержимое системы сборки и свойства сборки, которые отличаются в зависимости от generation-time context, включая:

Платформу (например, Windows, APPLE, Linux).
Конфигурацию сборки (например, Debug, Release, Coverage).
Компилятор (например, MSVC, GCC, Clang) и его версию.
Язык исходных файлов, которые компилируются.
Доступные возможности компиляции (например, CXX variadic templates).
Политики CMake.

Протокол призван предоставлять информацию инструментарию, чтобы удовлетворить нескольким потребностям:

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

Работа

Запустите cmake(1) в режиме сервера, передав путь к каталогу сборки для обработки:

cmake -E server (--debug|--pipe=<NAMED_PIPE>)

Сервер будет обмениваться данными через stdin/stdout (с параметром --debug) или через именованную трубу (с параметром --pipe=<NAMED_PIPE>). Обратите внимание, что «именованная труба» относится к сокету доменной области на Unix и к именованной трубе в Windows.

При подключении к серверу (через именованную трубу или путем запуска в режиме --debug), сервер ответит сообщением hello:

[== "CMake Server" ==[
{"supportedProtocolVersions":[{"major":1,"minor":0}],"type":"hello"}
]== "CMake Server" ==]

Сообщения, отправляемые и получаемые процессом, обернуты в магические строки:

[== "CMake Server" ==[
{
  ... some JSON message ...
}
]== "CMake Server" ==]

Сервер теперь готов принимать дальнейшие запросы через именованную трубу или stdin.

Отладка

Режим сервера CMake можно запросить предоставить статистику о времени выполнения и т. п. или вывести копию ответа в файл. Это делается путем передачи JSON-объекта «debug» в качестве дочернего элемента запроса.

Объект debug поддерживает ключ «showStats», который принимает булево значение и заставляет серверный режим возвращать объект «zzzDebug» со статистикой в качестве части ответа. «dumpToFile» принимает строковое значение и заставляет сервер CMake скопировать ответ в указанный файл.

Это ответ от сервера CMake с параметром «showStats», установленным в значение true:

[== "CMake Server" ==[
{
  "cookie":"",
  "errorMessage":"Waiting for type \"handshake\".",
  "inReplyTo":"unknown",
 "type":"error",
  "zzzDebug": {
    "dumpFile":"/tmp/error.txt",
    "jsonSerialization":0.011016,
    "size":111,
    "totalTime":0.025995
  }
}
]== "CMake Server" ==]

Сервер скопировал этот ответ в файл /tmp/error.txt и потратил 0,011 секунды на преобразование JSON-ответа в строку, а на обработку запроса в целом ушло 0,025 секунды. Размер ответа составляет 111 байтов.

Протокол API

Общий формат сообщений

Все сообщения должны иметь значение «type», которое определяет тип сообщения, передаваемого туда или обратно. Например, начальное сообщение, отправленное сервером, имеет тип «hello». Сообщения без типа сгенерируют ответ типа «error».

Все запросы, отправляемые на сервер, могут содержать значение «cookie». Это значение будет возвращено без изменений во всех ответах, вызванных запросом.

Все ответы будут содержать значение «inReplyTo», которое может быть пустым в случае ошибок синтаксического анализа, но в других случаях будет содержать тип запроса.

Тип «reply»

Этот тип используется сервером для ответа на запросы.

Сообщение может — в зависимости от типа исходного запроса — содержать значения.

Пример:

[== "CMake Server" ==[
{"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
]== "CMake Server" ==]

Тип «error»

Этот тип используется для возврата условия ошибки клиенту. Он будет содержать «errorMessage».

Пример:

[== "CMake Server" ==[
{"cookie":"","errorMessage":"Protocol version not supported.","inReplyTo":"handshake","type":"error"}
]== "CMake Server" ==]

Тип «progress»

Когда сервер занят длительное время, вежливо отправлять клиенту ответы типа «progress». Они будут содержать «progressMessage» со строкой, описывающей выполняемое действие, а также «progressMinimum», «progressMaximum» и «progressCurrent» с целочисленными значениями, описывающими диапазон прогресса.

Сообщения типа «progress» будут следовать за другими сообщениями «progress» или сообщением типа «reply» или «error», которые завершают запрос.

Сообщения «progress» не могут быть отправлены после сообщения «reply» или «error» для запроса, который вызвал ответы, пока они не будут переданы.

Тип «message»

Сообщение генерируется, когда сервер обрабатывает запрос и создаёт какой-либо вывод, который должен быть показан пользователю. В сообщении содержится «message» с фактическим текстом для отображения и «title» с предлагаемым заголовком диалогового окна.

Пример:

[== "CMake Server" ==[
{"cookie":"","message":"Something happened.","title":"Title Text","inReplyTo":"handshake","type":"message"}
]== "CMake Server" ==]

Тип «signal»

Сервер может отправлять сигналы, когда обнаруживает изменения в состоянии системы. Сигналы имеют тип «signal», пустые поля «cookie» и «inReplyTo» и всегда содержат «name», чтобы показать, какой сигнал был отправлен.

Конкретные сигналы

Сигнал «dirty»

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

Сигнал «dirty» может выглядеть так:

[== "CMake Server" ==[
{
  "cookie":"",
  "inReplyTo":"",
  "name":"dirty",
  "type":"signal"}
]== "CMake Server" ==]

Сигнал «fileChange»

Сигнал «fileChange» отправляется всякий раз, когда изменяется отслеживаемый файл. Он содержит «path», который был изменён, и список «properties» с типом обнаруженного изменения. Возможные изменения — «change» и «rename».

Сигнал «fileChange» выглядит так:

[== "CMake Server" ==[
{
  "cookie":"",
  "inReplyTo":"",
  "name":"fileChange",
  "path":"/absolute/CMakeLists.txt",
  "properties":["change"],
  "type":"signal"}
]== "CMake Server" ==]

Конкретные типы сообщений

Тип «hello»

Первое сообщение, отправленное сервером CMake при запуске, имеет тип «hello». Это единственное сообщение, отправляемое сервером, которое не имеет тип «reply», «progress» или «error».

Он будет содержать «supportedProtocolVersions» с массивом поддерживаемых версий протокола сервера CMake. Это JSON-объекты с ключами «major» и «minor», содержащими неотрицательные целочисленные значения. Некоторые версии могут быть помечены как экспериментальные. Они будут содержать ключ «isExperimental», установленный в значение true. Для их включения требуется специальный аргумент командной строки при запуске сервера CMake.

В пределах версии «major» все версии «minor» полностью совместимы с предыдущими версиями. Новые версии «minor» могут добавлять функциональность таким образом, что существующие клиенты той же версии «major» по-прежнему будут работать, при условии, что они проигнорируют ключи в выводе, о которых они не знают.

Пример:

[== "CMake Server" ==[
{"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"}
]== "CMake Server" ==]

Тип «handshake»

Первый запрос, который клиент может отправить серверу, имеет тип «handshake».

Этот запрос должен передать одну из поддерживаемых версий «supportedProtocolVersions» ответа типа «hello», полученного ранее, обратно на сервер в поле «protocolVersion». Указание версии «major» запрошенной версии протокола заставит сервер использовать последнюю версию «minor» этого протокола. Используйте это, если вам явно не нужна зависимость от конкретной версии «minor».

Версия протокола 1.0 требует установки следующих атрибутов:

«sourceDirectory» с путём к исходным файлам
«buildDirectory» с путём к каталогу сборки
«generator» с именем генератора
«extraGenerator» (необязательно!) с дополнительным генератором для использования
«platform» с платформой генератора (если поддерживается генератором)
«toolset» с набором инструментов генератора (если поддерживается генератором)

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

Пример:

[== "CMake Server" ==[
{"cookie":"zimtstern","type":"handshake","protocolVersion":{"major":0},
 "sourceDirectory":"/home/code/cmake", "buildDirectory":"/tmp/testbuild",
 "generator":"Ninja"}
]== "CMake Server" ==]

что приведёт к ответу типа «reply»:

[== "CMake Server" ==[
{"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"}
]== "CMake Server" ==]

указывающее, что сервер готов к работе.

Тип «globalSettings»

Этот запрос можно отправить после первоначального рукопожатия. Он вернёт JSON-структуру с информацией о состоянии CMake.

Пример:

[== "CMake Server" ==[
{"type":"globalSettings"}
]== "CMake Server" ==]

что приведёт к ответу типа «reply»:

[== "CMake Server" ==[
{
  "buildDirectory": "/tmp/test-build",
  "capabilities": {
    "generators": [
      {
        "extraGenerators": [],
        "name": "Watcom WMake",
        "platformSupport": false,
        "toolsetSupport": false
      },
      <...>
    ],
    "serverMode": false,
    "version": {
      "isDirty": false,
      "major": 3,
      "minor": 6,
      "patch": 20160830,
      "string": "3.6.20160830-gd6abad",
      "suffix": "gd6abad"
    }
  },
  "checkSystemVars": false,
  "cookie": "",
  "extraGenerator": "",
  "generator": "Ninja",
  "debugOutput": false,
  "inReplyTo": "globalSettings",
  "sourceDirectory": "/home/code/cmake",
  "trace": false,
  "traceExpand": false,
  "type": "reply",
  "warnUninitialized": false,
  "warnUnused": false,
  "warnUnusedCli": true
}
]== "CMake Server" ==]

Тип «setGlobalSettings»

Этот запрос можно отправить для изменения атрибутов глобальных настроек. Неизвестные атрибуты будут проигнорированы. Все только для чтения атрибуты, сообщённые «globalSettings», такие как capabilities, buildDirectory, generator, extraGenerator и sourceDirectory. Любая попытка установить их также будет проигнорирована.

Все остальные настройки будут изменены.

Сервер ответит пустым сообщением reply или ошибкой.

Пример:

[== "CMake Server" ==[
{"type":"setGlobalSettings","debugOutput":true}
]== "CMake Server" ==]

CMake ответит так:

[== "CMake Server" ==[
{"inReplyTo":"setGlobalSettings","type":"reply"}
]== "CMake Server" ==]

Тип «configure»

Этот запрос выполнит конфигурацию проекта для сборки.

Для конфигурации каталога сборки, уже содержащего файлы CMake, достаточно установить «buildDirectory» через «setGlobalSettings». Для создания нового каталога сборки также необходимо установить «currentGenerator» и «sourceDirectory» через «setGlobalSettings» в дополнение к «buildDirectory».

Вы можете передать список строк в «configure» через ключ «cacheArguments». Эти строки будут интерпретированы аналогично аргументам командной строки, относящимся к обработке кэша, которые передаются клиенту CMake командной строки.

Пример:

[== "CMake Server" ==[
{"type":"configure", "cacheArguments":["-Dsomething=else"]}
]== "CMake Server" ==]

CMake ответит примерно так (после некоторого времени отображения прогресса):

[== "CMake Server" ==[
{"cookie":"","inReplyTo":"configure","type":"reply"}
]== "CMake Server" ==]

Тип «compute»

Этот запрос сгенерирует файлы системы сборки в каталоге сборки и доступен только после успешной конфигурации проекта с помощью «configure».

Пример:

[== "CMake Server" ==[
{"type":"compute"}
]== "CMake Server" ==]

CMake ответит (после отображения информации о прогрессе):

[== "CMake Server" ==[
{"cookie":"","inReplyTo":"compute","type":"reply"}
]== "CMake Server" ==]

Тип «codemodel»

Запрос «codemodel» можно использовать после успешного выполнения «compute».

Он отобразит полную структуру проекта, как она известна CMake.

Ответ будет содержать ключ «configurations», который будет содержать список объектов конфигурации. Объекты конфигурации используются для различения различных конфигураций, которые могут быть включены в каталог сборки. Хотя большинство генераторов поддерживают только одну конфигурацию, другие могут поддерживать несколько.

Каждый объект конфигурации может иметь следующие ключи:

«name»: содержит имя конфигурации. Имя может быть пустым.
«projects»: содержит список объектов проекта, по одному для каждого проекта сборки.

Объекты проекта определяют один (под-)проект, определённый в системе сборки CMake.

Каждый объект проекта может иметь следующие ключи:

«name»: содержит имя (под-)проекта.
«minimumCMakeVersion»: содержит минимальную версию CMake, разрешенную для этого проекта; null, если проект не указывает её.
«hasInstallRule»: true, если проект содержит какие-либо правила установки, иначе false.
«sourceDirectory»: содержит текущий каталог исходных файлов.
«buildDirectory»: содержит текущий каталог сборки.
«targets»: содержит список объектов целевых объектов системы сборки.

Объекты цели определяют отдельные целевые объекты сборки для определённой конфигурации.

Каждый объект цели может иметь следующие ключи:

«name»: содержит имя цели.
«type»: определяет тип сборки цели. Возможные значения: «STATIC_LIBRARY», «MODULE_LIBRARY», «SHARED_LIBRARY», «OBJECT_LIBRARY», «EXECUTABLE», «UTILITY» и «INTERFACE_LIBRARY».
«fullName»: содержит полное имя результата сборки (включая расширения и т. д.).
«sourceDirectory»: содержит текущий каталог исходных файлов.
«buildDirectory»: содержит текущий каталог сборки.
«isGeneratorProvided»: true, если цель автоматически создана генератором, иначе false.
«hasInstallRule»: true, если цель содержит какие-либо правила установки, иначе false.
«installPaths»: полный путь к целевым каталогам, определённым правилами установки цели.
«artifacts»: содержит список артефактов сборки. Список отсортирован по важности артефактов (например, файл .DLL в Windows идёт перед файлом .PDB).
«linkerLanguage»: содержит язык линковщика, используемого для создания артефакта.
«linkLibraries»: содержит список библиотек для линковки. Это значение закодировано в формате оболочки системы.
«linkFlags»: содержит список флагов, передаваемых линковщику. Это значение закодировано в формате оболочки системы.
«linkLanguageFlags»: содержит флаги для компилятора, использующего linkerLanguage. Это значение закодировано в формате оболочки системы.
«frameworkPath»: путь к фреймворку (на компьютерах Apple). Это значение закодировано в формате оболочки системы.
«linkPath»: путь к линковке. Это значение закодировано в формате оболочки системы.
«sysroot»: путь к sysroot.
«fileGroups»: содержит исходные файлы, составляющие цель.

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

Каждый объект fileGroup может содержать следующие ключи:

«language»: содержит язык программирования, используемый всеми файлами в группе.
«compileFlags»: содержит строку со всеми флагами, передаваемыми компилятору при построении любого из файлов в этой группе. Это значение закодировано в формате оболочки системы.
«includePath»: содержит список путей включения. Каждый путь включения — это объект, содержащий «path» с фактическим путём включения и «isSystem» с логическим значением, указывающим, является ли это обычным включением или системным включением. Это значение закодировано в формате оболочки системы.
«defines»: содержит список определений в формате «SOMEVALUE» или «SOMEVALUE=42». Это значение закодировано в формате оболочки системы.
«sources»: содержит список исходных файлов.

Все пути к файлам в fileGroup являются либо абсолютными, либо относительными к sourceDirectory цели.

Пример:

[== "CMake Server" ==[
{"type":"codemodel"}
]== "CMake Server" ==]

CMake ответит:

[== "CMake Server" ==[
{
  "configurations": [
    {
      "name": "",
      "projects": [
        {
          "buildDirectory": "/tmp/build/Source/CursesDialog/form",
          "name": "CMAKE_FORM",
          "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
          "targets": [
            {
              "artifacts": [ "/tmp/build/Source/CursesDialog/form/libcmForm.a" ],
              "buildDirectory": "/tmp/build/Source/CursesDialog/form",
              "fileGroups": [
                {
                  "compileFlags": "  -std=gnu11",
                  "defines": [ "CURL_STATICLIB", "LIBARCHIVE_STATIC" ],
                  "includePath": [ { "path": "/tmp/build/Utilities" }, <...> ],
                  "isGenerated": false,
                  "language": "C",
                  "sources": [ "fld_arg.c", <...> ]
                }
              ],
              "fullName": "libcmForm.a",
              "linkerLanguage": "C",
              "name": "cmForm",
              "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form",
              "type": "STATIC_LIBRARY"
            }
          ]
        },
        <...>
      ]
    }
  ],
  "cookie": "",
  "inReplyTo": "codemodel",
  "type": "reply"
}
]== "CMake Server" ==]

Тип «ctestInfo»

Запрос «ctestInfo» можно использовать после успешного выполнения «compute».

Он отобразит полную структуру тестов проекта, как она известна CMake.

Каждый объект конфигурации может иметь следующие ключи:

«name»: содержит имя конфигурации. Имя может быть пустым.
«projects»: содержит список объектов проекта, по одному для каждого проекта сборки.

Объекты проекта определяют один (под-)проект, определённый в системе сборки CMake.

Каждый объект проекта может иметь следующие ключи:

«name»: содержит имя (под-)проекта.
«ctestInfo»: содержит список объектов тестов.

Каждый объект теста может иметь следующие ключи:

«ctestName»: содержит имя теста.
«ctestCommand»: содержит команду теста.
«properties»: содержит список объектов свойств теста.

Каждый объект свойства теста может иметь следующие ключи:

«key»: содержит ключ свойства теста.
«value»: содержит значение свойства теста.

Тип «cmakeInputs»

Запросы «cmakeInputs» сообщат файлы, используемые CMake как часть самой системы сборки.

Этот запрос доступен только после успешной конфигурации проекта с помощью «configure».

Пример:

[== "CMake Server" ==[
{"type":"cmakeInputs"}
]== "CMake Server" ==]

CMake ответит следующей информацией:

[== "CMake Server" ==[
{"buildFiles":
  [
    {"isCMake":true,"isTemporary":false,"sources":["/usr/lib/cmake/...", ... ]},
    {"isCMake":false,"isTemporary":false,"sources":["CMakeLists.txt", ...]},
    {"isCMake":false,"isTemporary":true,"sources":["/tmp/build/CMakeFiles/...", ...]}
  ],
  "cmakeRootDirectory":"/usr/lib/cmake",
  "sourceDirectory":"/home/code/src/cmake",
  "cookie":"",
  "inReplyTo":"cmakeInputs",
  "type":"reply"
}
]== "CMake Server" ==]

Все имена файлов относительны к каталогу верхнего уровня исходных файлов или являются абсолютными.

Список файлов, для которых «isCMake» установлено в true, входит в установку CMake.

Список файлов, для которых «isTemporary» установлено в true, входит в каталог сборки и не сохранится при очистке каталога сборки.

Тип «cache»

Запрос «cache» отобразит кэшированные значения конфигурации.

Пример:

[== "CMake Server" ==[
{"type":"cache"}
]== "CMake Server" ==]

CMake ответит следующим выводом:

[== "CMake Server" ==[
{
  "cookie":"","inReplyTo":"cache","type":"reply",
  "cache":
  [
    {
      "key":"SOMEVALUE",
      "properties":
      {
        "ADVANCED":"1",
        "HELPSTRING":"This is not helpful"
      }
      "type":"STRING",
      "value":"TEST"}
  ]
}
]== "CMake Server" ==]

Вывод может быть ограничен списком ключей путём передачи массива имён ключей в необязательное поле «keys» запроса «cache».

Тип «fileSystemWatchers»

Сервер может отслеживать изменения в файловой системе. Команда «fileSystemWatchers» сообщит об отслеживаемых файлах и каталогах.

Пример:

[== "CMake Server" ==[
{"type":"fileSystemWatchers"}
]== "CMake Server" ==]

CMake ответит следующим выводом:

[== "CMake Server" ==[
{
  "cookie":"","inReplyTo":"fileSystemWatchers","type":"reply",
  "watchedFiles": [ "/absolute/path" ],
  "watchedDirectories": [ "/absolute" ]
}
]== "CMake Server" ==]

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