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», который принимает значение boolean и заставляет режим сервера возвращать объект «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 перечислен перед файлом .PDB в Windows).
«linkerLanguage»: содержит язык компоновщика, используемый для создания артефакта.
«linkLibraries»: список библиотек для компоновки. Это значение закодировано в формате оболочки системы.
«linkFlags»: список флагов для передачи компоновщику. Это значение закодировано в формате оболочки системы.
«linkLanguageFlags»: флаги для компилятора, использующего язык компоновщика. Это значение закодировано в формате оболочки системы.
«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.15/manual/cmake-server.7.html