Spec-Zone.ru › CMake 3.8

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).
  • Конфигурацию сборки (например, 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>).

При подключении к серверу (через именованную трубу или запуском в режиме --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, потратив на преобразование JSON-ответа в строку 0,011 секунды, а на обработку запроса в целом – 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»
флаги для компилятора, использующего язык линковщика. Это значение закодировано в формате оболочки системы.
«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.8/manual/cmake-server.7.html

Spec-Zone.ru

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