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 (|). Поскольку литеральные блочные скаляры не поддерживают экранирование, обратные слэши и непечатаемые символы кодируются на уровне приложения:

• \\ кодирует обратный слэш.
• \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, содержащий текст сообщения, представленный с помощью нашей кодировки блоков текста.

Тип события 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, содержащий вывод от сборки тестового проекта, представленный с помощью нашей кодировки блоков текста. Это содержит вывод сборки как из 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

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