Spec-Zone.ru › CMake 3.9

cmake-server(7)

  • Введение
  • Работа
  • Отладка
  • Протокол API
    • Общий формат сообщений
      • Тип «reply»
      • Тип «error»
      • Тип «progress»
      • Тип «message»
      • Тип «signal»
    • Конкретные сигналы
      • Сигнал «dirty»
      • Сигнал «fileChange»
    • Конкретные типы сообщений
      • Тип «hello»
      • Тип «handshake»
      • Тип «globalSettings»
      • Тип «setGlobalSettings»
      • Тип «configure»
      • Тип «compute»
      • Тип «codemodel»
      • Тип «cmakeInputs»
      • Тип «cache»
      • Тип «fileSystemWatchers»

Введение

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

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

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

  • Платформу (например, Windows, APPLE, Linux).
  • Конфигурацию сборки (например, Отладка, Релиз, Покрытие).
  • Компилятор (например, 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>).

При подключении к серверу (через именованную трубу или запуская его в режиме --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.

Пример:

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

Тип «handshake»

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

Этот запрос должен передать одну из «supportedProtocolVersions» из ответа типа «hello», полученного ранее, обратно серверу в поле «protocolVersion».

Каждая версия протокола может запрашивать наличие дополнительных атрибутов.

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

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

Пример:

[== "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»
содержит имя (под-)проекта.
«sourceDirectory»
содержит текущий каталог исходных кодов.
«buildDirectory»
содержит текущий каталог сборки.
«targets»
содержит список объектов целевых систем сборки.

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

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

«name»
содержит имя целевой системы.
«type»
определяет тип сборки целевой системы. Возможные значения — «STATIC_LIBRARY», «MODULE_LIBRARY», «SHARED_LIBRARY», «OBJECT_LIBRARY», «EXECUTABLE», «UTILITY» и «INTERFACE_LIBRARY».
«fullName»
содержит полное имя результата сборки (включая расширения и т. д.).
«sourceDirectory»
содержит текущий каталог исходных кодов.
«buildDirectory»
содержит текущий каталог сборки.
«artifacts»
список артефактов сборки. Список отсортирован по важности артефактов (например, файл .DLL перечислен перед файлом .PDB в Windows).
«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" ==]

Тип «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.9/manual/cmake-server.7.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API