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

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