cmake-configure-log(7)

• Введение

• Структура лога

  • Версионирование лога
  • Кодировка блоков текста

• Типы событий

  • Тип события message

    • message-v1 Событие

  • Тип события try_compile

    • try_compile-v1 Событие

  • Тип события try_run

    • try_run-v1 Событие

Введение

CMake записывает текущий лог, известный как лог конфигурации, определённых событий, происходящих во время шага конфигурации. Лого конфигурации не содержит лога всего вывода, ошибок или сообщений, выведенных во время конфигурирования проекта. Это лог подробной информации о специфических событиях, таких как проверка инструментальной цепочки с помощью try_compile(), предназначенного для использования при отладке конфигурации дерева сборки.

Для использования человеком, эта версия CMake записывает лог конфигурации в файл:

${CMAKE_BINARY_DIR}/CMakeFiles/CMakeConfigureLog.yaml

Однако, местоположение и имя файла лога могут измениться в будущих версиях CMake. Инструменты, которые читают лог конфигурации, должны получить его местоположение, используя запрос configureLog к cmake-file-api(7). Подробности см. в разделе Версионирование лога ниже.

Структура лога

Лого конфигурации предназначен для чтения как машиной, так и человеком.

Файл лога представляет собой поток документов YAML, содержащий ноль или более документов YAML, разделённых маркерами документов. Каждый документ начинается с маркера --- строки документа, содержит одно YAML-отображение, которое записывает события из одного шага конфигурации CMake, и, если шаг конфигурации завершился нормально, заканчивается маркером ... строки документа:

---
events:
  -
    kind: "try_compile-v1"
    # (other fields omitted)
  -
    kind: "try_compile-v1"
    # (other fields omitted)
...

Новый документ добавляется в лог каждый раз, когда CMake конфигурирует дерево сборки и записывает новые события.

Ключи каждого корневого отображения документа:

events

Последовательность блоков YAML, соответствующая событиям, записанным в течение одного шага конфигурации CMake. Каждое событие — это YAML-узел, содержащий один из типов событий, описанных ниже.

Версионирование лога

Каждый из типов событий версионируется независимо. Набор ключей, которые содержит запись лога события, специфичен для его основной версии. Когда событие записывается, последняя версия типа события, известная текущей версии CMake, всегда записывается в лог.

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

• Будущая версия CMake может добавить новый тип события или версию.
• Если существующее дерево сборки переконфигурируется с использованием другой версии CMake, лог может содержать разные версии одного и того же типа события.
• Если запросы cmake-file-api(7) запрашивают одну или несколько версий объекта configureLog, лог может содержать несколько записей для одного и того же события, каждая с разной версией её типа события.

IDE должны сделать запрос cmake-file-api(7) запроса конкретной версии объекта configureLog перед запуском CMake, а затем читать лог конфигурации только так, как описано в ответе file-api.

Кодировка блоков текста

Для обеспечения удобочитаемости лога, блоки текста всегда представляются с использованием YAML literal block scalars (|). Поскольку literal block scalars не поддерживают экранирование, обратные слэши и непропечатываемые символы кодируются на уровне приложения:

• \\ кодирует обратный слэш.
• \xXX кодирует байт, используя две шестнадцатеричные цифры, XX.

Типы событий

Каждый тип события представлен YAML-отображением вида:

kind: "<kind>-v<major>"
backtrace:
  - "<file>:<line> (<function>)"
checks:
  - "Checking for something"
#...event-specific keys...

Ключи, общие для всех событий:

kind

Строка, идентифицирующая тип события и основную версию.

backtrace

Последовательность блоков YAML, сообщающая о стеке вызовов расположений исходного кода CMake, в котором произошло событие, от последнего к первому. Каждый узел — строка, определяющая одно расположение в формате <file>:<line> (<function>).

checks

Необязательный ключ, присутствующий, когда событие произошло с хотя бы одним ожидающим message(CHECK_START). Его значение — YAML-последовательность блоков, сообщающая о стеке ожидающих проверок от последней к первой. Каждый узел — строка, содержащая сообщение ожидающей проверки.

Дополнительные ключи отображения специфичны для каждого (версионированного) типа события, описаны ниже.

Тип события message

Команда message(CONFIGURE_LOG) записывает message события.

Существует только одна основная версия события message, версия 1.

message-v1 Событие

Событие message-v1 — YAML-отображение:

kind: "message-v1"
backtrace:
  - "CMakeLists.txt:123 (message)"
checks:
  - "Checking for something"
message: |
  # ...

Ключи, специфичные для отображений message-v1:

message

YAML literal block scalar, содержащий текст сообщения, представленный с помощью нашей кодировки блоков текста.

Тип события try_compile

Команда try_compile() записывает try_compile события.

Существует только одна основная версия события try_compile, версия 1.

try_compile-v1 Событие

Событие try_compile-v1 — YAML-отображение:

kind: "try_compile-v1"
backtrace:
  - "CMakeLists.txt:123 (try_compile)"
checks:
  - "Checking for something"
description: "Explicit LOG_DESCRIPTION"
directories:
  source: "/path/to/.../TryCompile-01234"
  binary: "/path/to/.../TryCompile-01234"
cmakeVariables:
  SOME_VARIABLE: "Some Value"
buildResult:
  variable: "COMPILE_RESULT"
  cached: true
  stdout: |
    # ...
  exitCode: 0

Ключи, специфичные для отображений try_compile-v1:

description

Необязательный ключ, присутствующий, когда использовался параметр LOG_DESCRIPTION <text>. Его значение — строка, содержащая описание <text>.

directories

Отображение, описывающее каталоги, связанные с попыткой компиляции. Имеет следующие ключи:

source

Строка, указывающая исходную директорию проекта try_compile().

binary

Строка, указывающая бинарную директорию проекта try_compile(). Для вызовов, не относящихся к проектам, это часто совпадает с исходной директорией.

cmakeVariables

Необязательный ключ, присутствующий, когда CMake распространяет переменные в проект теста, либо автоматически, либо из-за переменной CMAKE_TRY_COMPILE_PLATFORM_VARIABLES. Его значение — отображение от имён переменных к их значениям.

buildResult

Отображение, описывающее результат компиляции тестового кода. Имеет следующие ключи:

variable

Строка, определяющая имя переменной CMake, хранящей результат попытки построения тестового проекта.

cached

Булево значение, указывающее, хранится ли вышеупомянутый результат variable в кэше CMake.

stdout

YAML literal block scalar, содержащий вывод от построения тестового проекта, представленный с помощью нашей кодировки блоков текста. Это содержит вывод сборки из stdout и stderr.

exitCode

Целое число, определяющее код завершения утилиты сборки при попытке построения тестового проекта.

Тип события try_run

Команда try_run() записывает try_run события.

Существует только одна основная версия события try_run, версия 1.

try_run-v1 Событие

Событие try_run-v1 — YAML-отображение:

kind: "try_run-v1"
backtrace:
  - "CMakeLists.txt:456 (try_run)"
checks:
  - "Checking for something"
description: "Explicit LOG_DESCRIPTION"
directories:
  source: "/path/to/.../TryCompile-56789"
  binary: "/path/to/.../TryCompile-56789"
buildResult:
  variable: "COMPILE_RESULT"
  cached: true
  stdout: |
    # ...
  exitCode: 0
runResult:
  variable: "RUN_RESULT"
  cached: true
  stdout: |
    # ...
  stderr: |
    # ...
  exitCode: 0

Ключи, специфичные для отображений try_run-v1 включают те, что документированы в событии try_compile-v1, плюс:

runResult

Отображение, описывающее результат выполнения тестового кода. Оно имеет следующие ключи:

variable

Строка, определяющая имя переменной CMake, хранящей результат попытки запустить исполняемый файл теста.

cached

Булево значение, указывающее, хранится ли вышеуказанный результат variable в кэше CMake.

stdout

Необязательный ключ, присутствующий, когда тестовый проект был успешно собран. Его значение — YAML-литеральный блок скаляр, содержащий вывод от выполнения исполняемого файла теста, представленный с помощью нашего Кодирования текстовых блоков.

Если RUN_OUTPUT_VARIABLE был использован, stdout и stderr собираются вместе, поэтому это будет содержать оба. В противном случае это будет содержать только вывод stdout.

stderr

Необязательный ключ, присутствующий, когда тестовый проект был успешно собран, и опция RUN_OUTPUT_VARIABLE не использовалась. Его значение — YAML-литеральный блок скаляр, содержащий вывод от выполнения исполняемого файла теста, представленный с помощью нашего Кодирования текстовых блоков.

Если RUN_OUTPUT_VARIABLE использовалась, stdout и stderr собираются вместе в ключе stdout, и этот ключ не будет присутствовать. В противном случае это будет содержать вывод stderr.

exitCode

Необязательный ключ, присутствующий, когда тестовый проект был успешно собран. Его значение — целое число, определяющее код завершения или строка с сообщением об ошибке при попытке запустить исполняемый файл теста.