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

Тип «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», чтобы показать, какой сигнал был отправлен.

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

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

Сигнал «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», — это все возможности, buildDirectory, generator, extraGenerator и sourceDirectory. Любая попытка установить их также будет проигнорирована.

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

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

Пример:

[== "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» со значением 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–2019 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.12/manual/cmake-server.7.html