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, и затем читать лог конфигурации только так, как это описано в ответе 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

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