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

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