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

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