cmake-server(7)

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

Введение

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», которое может быть пустым в случае ошибок парсинга, но будет содержать тип сообщения запроса во всех остальных случаях.

Тип «ответ»

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

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

Пример:

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

Тип «ошибка»

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

Пример:

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

Тип «прогресс»

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

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

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

Тип «сообщение»

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

Пример:

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

Тип «сигнал»

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

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

Сервер CMake может отправлять сигналы с указанными ниже именами:

Сигнал «dirty»

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

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

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

Сигнал «fileChange»

Сигнал «fileChange» отправляется всякий раз, когда изменяется отслеживаемый файл. Он содержит путь, который изменился, и список свойств с типом изменения, который был обнаружен. Возможные изменения — «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», — это все возможности, 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» со значением bool, указывающим, является ли это обычным путем включения или системным. Это значение закодировано в родном формате оболочки системы.
«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.14/manual/cmake-server.7.html