cmake-server(7)

• Введение
• Работа
• Отладка

• API протокола

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

    • Тип “reply”
    • Тип “error”
    • Тип “progress”
    • Тип “message”
    • Тип “signal”

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

    • Сигнал “dirty”
    • Сигнал “fileChange”

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

    • Тип “hello”
    • Тип “handshake”
    • Тип “globalSettings”
    • Тип “setGlobalSettings”
    • Тип “configure”
    • Тип “compute”
    • Тип “codemodel”
    • Тип “ctestInfo”
    • Тип “cmakeInputs”
    • Тип “cache”
    • Тип “fileSystemWatchers”

Введение

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.

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

1. Предоставить полную и легко парсируемую информацию обо всех данных, относящихся к инструменту по отношению к исходному коду. Инструментам не нужно будет парсить сгенерированные системы сборки, чтобы получить, например, каталоги включения или определения компиляции.
2. Семантическая информация о самой системе сборки CMake.
3. Обеспечение стабильного интерфейса для чтения информации в кэше CMake.
4. Информация для определения, когда 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», это все возможности, каталог сборки, генератор, дополнительный генератор и каталог исходного кода. Любая попытка установить эти значения также будет проигнорирована.

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

Сервер ответит пустым сообщением 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»

содержит список объектов целевых систем сборки.

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

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

«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.

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

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

«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" ==]