ctest(1)

• Синопсис
• Описание
• Запуск тестов
• Просмотр справки
• Сопоставление меток
• Резюме меток и подпроектов
• Режим сборки и тестирования

• Клиент панели мониторинга

  • Шаги клиента панели мониторинга
  • Режимы клиента панели мониторинга
  • Клиент панели мониторинга через командную строку CTest
  • Клиент панели мониторинга через сценарий CTest

• Настройка клиента панели мониторинга

  • Шаг CTest Start
  • Шаг CTest Update
  • Шаг CTest Configure
  • Шаг CTest Build
  • Шаг CTest Test
  • Шаг CTest Coverage
  • Шаг CTest MemCheck
  • Шаг CTest Submit
• Отобразить в формате JSON Object Model

• Распределение ресурсов

  • Файл спецификации ресурсов
  • Свойство групп ресурсов
  • Переменные окружения
  • Динамически сгенерированный файл спецификации ресурсов
• Интеграция с сервером задач
• См. также

Синопсис

Run Tests
 ctest [<options>] [--test-dir <path-to-build>]

Build and Test Mode
 ctest --build-and-test <path-to-source> <path-to-build>
       --build-generator <generator> [<options>...]
      [--build-options <opts>...]
      [--test-command <command> [<args>...]]

Dashboard Client
 ctest -D <dashboard>         [-- <dashboard-options>...]
 ctest -M <model> -T <action> [-- <dashboard-options>...]
 ctest -S <script>            [-- <dashboard-options>...]
 ctest -SP <script>           [-- <dashboard-options>...]

View Help
 ctest --help[-<topic>]

Описание

Исполняемый файл ctest — это программа-драйвер тестов CMake. Деревья сборки, сгенерированные CMake для проектов, использующих команды enable_testing() и add_test(), имеют поддержку тестирования. Эта программа будет запускать тесты и сообщать результаты.

Запуск тестов

--preset <preset>, --preset=<preset>

Используйте набор тестов для указания параметров тестов. Директория двоичных файлов проекта определяется по ключу configurePreset. Текущая рабочая директория должна содержать файлы наборов тестов CMake. Дополнительные сведения см. в preset.

--list-presets

Отображает доступные наборы тестов. Текущая рабочая директория должна содержать файлы наборов тестов CMake.

-C <cfg>, --build-config <cfg>

Выберите конфигурацию для тестирования.

Некоторые сгенерированные CMake деревья сборки могут иметь несколько конфигураций сборки в одном дереве. Этот параметр позволяет указать, какая из них должна быть протестирована. Примеры конфигураций: Debug и Release.

--progress

Включить краткий вывод прогресса тестов.

Когда вывод ctest отправляется напрямую в терминал, прогресс по набору тестов отображается путём обновления той же строки, а не вывода сообщений начала и конца каждого теста в новой строке. Это может существенно уменьшить объём вывода результатов тестов. Сообщения об успешном завершении теста всё равно выводятся в отдельной строке для неудачных тестов, а также будет регистрироваться сводная информация по результатам всех тестов.

Этот параметр также можно включить, задав переменную окружения CTEST_PROGRESS_OUTPUT.

-V, --verbose

Включить подробный вывод результатов тестов.

Вывод тестов обычно подавляется, и отображается только сводная информация. Этот параметр отобразит весь вывод тестов.

-VV, --extra-verbose

Включить более подробный вывод результатов тестов.

Вывод тестов обычно подавляется, и отображается только сводная информация. Этот параметр отобразит ещё больше вывода тестов.

--debug

Отображение более подробной внутренней информации CTest.

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

--output-on-failure

Вывести всё, что вывела программа теста, если тест завершится неудачно. Этот параметр также можно включить, задав переменную окружения CTEST_OUTPUT_ON_FAILURE

--stop-on-failure

Остановить выполнение тестов при первом сбое.

-F

Включить failover.

Этот параметр позволяет CTest возобновить выполнение набора тестов, который был прерван ранее. Если прерывания не произошло, параметр -F не окажет никакого влияния.

-j [<level>], --parallel [<level>]

Запустить тесты параллельно, при необходимости ограничив уровень параллелизма.

Новое в версии 3.29: Параметр <level> может быть опущен, или 0, в этом случае:

• В Интеграции с сервером задач, параллелизм ограничен доступными маркерами задач.
• В противном случае, если значение опущено, параллелизм ограничен количеством процессоров или 2, в зависимости от того, что больше.
• В противном случае, если значение 0, параллелизм не ограничен.

Этот параметр также можно указать с помощью переменной окружения CTEST_PARALLEL_LEVEL.

Этот параметр можно использовать вместе со свойством теста PROCESSORS. См. Резюме меток и подпроектов.

--resource-spec-file <file>

Запустить CTest с включенным распределением ресурсов, используя указанный в <file> файл спецификации ресурсов.

Когда ctest запускается как клиент панели мониторинга, это устанавливает параметр ResourceSpecFile шага CTest Test.

--test-load <level>

При запуске тестов параллельно (например, с -j) стараться не запускать тесты, когда нагрузка на ЦП может превысить заданный порог.

Когда ctest запускается как клиент панели мониторинга, это устанавливает параметр TestLoad шага CTest Test.

-Q, --quiet

Сделать CTest тихим.

Этот параметр подавит весь вывод. Файл журнала вывода всё равно будет создан, если указан параметр --output-log. Параметры, такие как --verbose, --extra-verbose и --debug, игнорируются, если указан --quiet.

-O <file>, --output-log <file>

Вывод в файл журнала.

Этот параметр указывает CTest записать весь вывод в файл журнала <file>.

--output-junit <file>

Новое в версии 3.21.

Записывать результаты тестов в формате JUnit.

Этот параметр сообщает CTest о записи результатов тестов в <file> в формате XML JUnit. Если <file> уже существует, он будет перезаписан. При использовании параметра -S для запуска скрипта панели мониторинга, используйте ключевое слово OUTPUT_JUNIT с командой ctest_test() вместо этого.

-N, --show-only[=<format>]

Отключить фактическое выполнение тестов.

Этот параметр сообщает CTest о выводе списка тестов, которые должны были бы выполняться, но фактически не будут. Полезно в сочетании с параметрами -R и -E.

Новое в версии 3.14: Параметр --show-only принимает значение <format>.

<format> может принимать следующие значения.

human

Вывод в удобном для чтения формате. Гарантия стабильности не предоставляется. Это значение по умолчанию.

json-v1

Выводить информацию о тестах в формате JSON. См. Показать в формате JSON Object Model.

-L <regex>, --label-regex <regex>

Выполнять тесты с метками, соответствующими регулярному выражению, как описано в string(REGEX).

Этот параметр сообщает CTest о выполнении только тех тестов, метки которых соответствуют заданному регулярному выражению. При указании нескольких параметров -L, тест будет выполнен только в том случае, если каждое регулярное выражение соответствует хотя бы одной из меток теста (т. е. несколько меток -L образуют отношение AND). См. Сопоставление меток.

-R <regex>, --tests-regex <regex>

Выполнять тесты, соответствующие регулярному выражению.

Этот параметр сообщает CTest о выполнении только тех тестов, имена которых соответствуют заданному регулярному выражению.

-E <regex>, --exclude-regex <regex>

Исключать тесты, соответствующие регулярному выражению.

Этот параметр сообщает CTest о НЕ выполнении тестов, имена которых соответствуют заданному регулярному выражению.

-LE <regex>, --label-exclude <regex>

Исключать тесты с метками, соответствующими регулярному выражению.

Этот параметр сообщает CTest о НЕ выполнении тестов, метки которых соответствуют заданному регулярному выражению. При указании нескольких параметров -LE, тест будет исключен только в том случае, если каждое регулярное выражение соответствует хотя бы одной из меток теста (т. е. несколько меток -LE образуют отношение AND). См. Сопоставление меток.

--tests-from-file <filename>

Новое в версии 3.29.

Выполнять тесты, перечисленные в заданном файле.

Этот параметр сообщает CTest о выполнении тестов, перечисленных в заданном файле. Файл должен содержать одно точное имя теста на строку. Строки, не точно соответствующие именам тестов, игнорируются. Этот параметр может использоваться совместно с другими параметрами, такими как -R, -E, -L или -LE.

--exclude-from-file <filename>

Новое в версии 3.29.

Исключать тесты, перечисленные в заданном файле.

Этот параметр сообщает CTest о НЕ выполнении тестов, перечисленных в заданном файле. Файл должен содержать одно точное имя теста на строку. Строки, не точно соответствующие именам тестов, игнорируются. Этот параметр может использоваться совместно с другими параметрами, такими как -R, -E, -L или -LE.

-FA <regex>, --fixture-exclude-any <regex>

Исключить фикстуры, соответствующие <regex>, из автоматического добавления тестов в набор тестов.

Если тест в наборе выполняемых тестов требует определённой фикстуры, тесты настройки и очистки этой фикстуры обычно автоматически добавляются в набор тестов. Этот параметр предотвращает добавление тестов настройки или очистки для фикстур, соответствующих <regex>. Обратите внимание, что все другие действия фикстуры сохраняются, включая зависимости тестов и пропуска тестов, имеющих тесты настройки фикстуры, которые завершились ошибкой.

-FS <regex>, --fixture-exclude-setup <regex>

Аналогично -FA, за исключением того, что исключаются только соответствующие тесты настройки.

-FC <regex>, --fixture-exclude-cleanup <regex>

Аналогично -FA, за исключением того, что исключаются только соответствующие тесты очистки.

-I [Start,End,Stride,test#,test#|Test file], --tests-information

Выполнить определенное количество тестов по номеру.

Этот параметр заставляет CTest выполнять тесты, начиная с номера Start, заканчивая номером End, с приращением Stride. Любые дополнительные номера после Stride рассматриваются как отдельные номера тестов. Start, End, или Stride могут быть пустыми. Дополнительно может быть задан файл, содержащий тот же синтаксис, что и в командной строке.

-U, --union

Взять объединение -I и -R.

При указании -R и -I по умолчанию выполняется пересечение тестов. Указав -U, выполняется объединение тестов вместо этого.

--rerun-failed

Выполнить только тесты, которые ранее завершились ошибкой.

Этот параметр сообщает CTest о выполнении только тех тестов, которые завершились ошибкой во время предыдущего выполнения. При указании этого параметра CTest игнорирует все остальные параметры, предназначенные для изменения списка выполняемых тестов ( -L, -R, -E, -LE, -I и т. д.). В случае, если CTest выполнится и ни один тест не завершится ошибкой, последующие вызовы CTest с параметром --rerun-failed выполнят набор тестов, которые последними завершились ошибкой (если таковые имеются).

--repeat <mode>:<n>

Повторять тесты в соответствии с заданным <mode> до <n> раз. Режимы:

until-fail

Требуется, чтобы каждый тест выполнялся <n> раз без ошибок, чтобы считался пройденным. Полезно для выявления случайных ошибок в тестовых кейсах.

until-pass

Разрешить каждому тесту выполняться до <n> раз, чтобы считался пройденным. Повторять тесты, если они завершаются ошибкой по любой причине. Полезно для переносимости случайных ошибок в тестовых кейсах.

after-timeout

Разрешить каждому тесту выполняться до <n> раз, чтобы считался пройденным. Повторять тесты только при возникновении таймаута. Полезно для переносимости случайных таймаутов в тестовых кейсах на загруженных машинах.

--repeat-until-fail <n>

Эквивалентно --repeat until-fail:<n>.

--max-width <width>

Установить максимальную ширину имени теста для вывода.

Установить максимальную ширину каждого имени теста для отображения в выводе. Это позволяет пользователю расширить вывод, чтобы избежать обрезания имени теста, что может быть очень раздражающим.

--interactive-debug-mode [0|1]

Установить интерактивный режим в 0 или 1.

Этот параметр заставляет CTest запускать тесты в интерактивном или неинтерактивном режиме. В режиме панели мониторинга (Experimental, Nightly, Continuous) значение по умолчанию - неинтерактивный режим. В неинтерактивном режиме переменная среды DASHBOARD_TEST_FROM_CTEST устанавливается.

До CMake 3.11 интерактивный режим в Windows мог позволять появлению системных всплывающих окон отладки. Теперь, из-за использования CTest libuv для запуска процессов тестов, все системные всплывающие окна отладки всегда блокируются.

--no-label-summary

Отключить сводку по времени для меток.

Этот параметр сообщает CTest о не выводе сводки по времени для каждой метки, связанной с выполненными тестами. Если на тесты нет меток, ничего дополнительного не выводится.

См. Сводка по меткам и подпроектам.

--no-subproject-summary

Отключить сводку по времени для подпроектов.

Этот параметр сообщает CTest о не выводе сводки по времени для каждого подпроекта, связанного с выполненными тестами. Если на тесты нет подпроектов, ничего дополнительного не выводится.

См. Сводка по меткам и подпроектам.

--test-dir <dir>

Новое в версии 3.20.

Укажите каталог, в котором следует искать тесты, обычно это каталог построения проекта CMake. Если не указано, используется текущий каталог.

--test-output-size-passed <size>

Новое в версии 3.4.

Ограничьте вывод для пройденных тестов до <size> байт.

--test-output-size-failed <size>

Новое в версии 3.4.

Ограничьте вывод для завершившихся с ошибкой тестов до <size> байт.

--test-output-truncation <mode>

Новое в версии 3.24.

Обрезать tail (по умолчанию), middle или head вывода теста при достижении максимального размера вывода.

--overwrite

Перезаписывает параметр конфигурации CTest.

По умолчанию CTest использует параметры конфигурации из файла конфигурации. Этот параметр перезапишет параметр конфигурации.

--force-new-ctest-process

Запускать дочерние экземпляры CTest в качестве новых процессов.

По умолчанию CTest запускает дочерние экземпляры CTest в рамках одного процесса. Если это поведение нежелательно, этот аргумент заставит запускать дочерние процессы CTest в новых процессах.

--schedule-random

Использовать случайный порядок для планирования тестов.

Этот параметр запустит тесты в случайном порядке. Он обычно используется для обнаружения неявных зависимостей в наборе тестов.

--submit-index

Устаревший параметр для старой функции сервера панели мониторинга Dart2. Не использовать.

--timeout <seconds>

Установить стандартный таймаут для тестов.

Этот параметр устанавливает таймаут для всех тестов, для которых таймаут не установлен с помощью свойства TIMEOUT.

--stop-time <time>

Установить время, по достижении которого все тесты должны прекратить выполнение.

Установите время суток, в которое все тесты должны выйти за пределы таймаута. Пример: 7:00:00 -0400. Принимается любой формат времени, понятный анализатору даты curl. Если не указана часовая зона, предполагается местное время.

--print-labels

Вывести все доступные метки тестов.

Этот параметр не будет запускать тесты, он просто выведет список всех меток, связанных с набором тестов.

--no-tests=<action>

Рассматривать отсутствие тестов либо как ошибку (если <action> установлено в error) либо игнорировать это (если <action> установлено в ignore).

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

Новое в версии 3.26.

Этот параметр также можно установить, задав переменную среды CTEST_NO_TESTS_ACTION.

Справка

Для вывода сведений о версии или выбранных страницах документации CMake используйте один из следующих параметров:

-version [<file>], --version [<file>], /V [<file>]

Показать заголовок с именем и версией программы и выйти. Вывод печатается в указанный <file> если задан.

-h, -H, --help, -help, -usage, /?

Вывести информацию об использовании и выйти.

Информация об использовании описывает базовый интерфейс командной строки и его параметры.

--help <keyword> [<file>]

Вывести справку по одному ключевому слову CMake.

<keyword> может быть свойством, переменной, командой, политикой, генератором или модулем.

Соответствующая запись справочника для <keyword> выводится в удобочитаемом текстовом формате. Вывод печатается в указанный <file> если задан.

Изменено в версии 3.28: До CMake 3.28 этот параметр поддерживал только имена команд.

--help-full [<file>]

Вывести все руководства по справке и выйти.

Все руководства выводятся в удобочитаемом текстовом формате. Вывод печатается в указанный <file> если задан.

--help-manual <man> [<file>]

Вывести одно руководство по справке и выйти.

Указанное руководство выводится в удобочитаемом текстовом формате. Вывод печатается в указанный <file> если задан.

--help-manual-list [<file>]

Вывести список доступных руководств по справке и выйти.

Список содержит все руководства, для которых справку можно получить, используя параметр --help-manual вместе с именем руководства. Вывод печатается в указанный <file> если задан.

--help-command <cmd> [<file>]

Вывести справку по одной команде и выйти.

Запись справочника cmake-commands(7) для <cmd> выводится в удобочитаемом текстовом формате. Вывод печатается в указанный <file> если задан.

--help-command-list [<file>]

Вывести список команд со справкой и выйти.

Список содержит все команды, для которых справку можно получить, используя параметр --help-command вместе с именем команды. Вывод печатается в указанный <file> если задан.

--help-commands [<file>]

Вывести руководство cmake-commands и выйти.

Руководство cmake-commands(7) выводится в удобочитаемом текстовом формате. Вывод печатается в указанный <file> если задан.

--help-module <mod> [<file>]

Вывести справку по одному модулю и выйти.

Запись справочника cmake-modules(7) для <mod> выводится в удобочитаемом текстовом формате. Вывод печатается в указанный <file> если задан.

--help-module-list [<file>]

Вывести список модулей со справкой и выйти.

Список содержит все модули, для которых справку можно получить, используя параметр --help-module вместе с именем модуля. Вывод печатается в указанный <file> если задан.

--help-modules [<file>]

Вывести руководство cmake-modules и выйти.

Руководство cmake-modules(7) выводится в удобочитаемом текстовом формате. Вывод печатается в указанный <file> если задан.

--help-policy <cmp> [<file>]

Вывести справку по одной политике и выйти.

Запись справочника cmake-policies(7) для <cmp> выводится в удобочитаемом текстовом формате. Вывод печатается в указанный <file> если задан.

--help-policy-list [<file>]

Вывести список политик со справкой и выйти.

Список содержит все политики, для которых справку можно получить, используя параметр --help-policy вместе с именем политики. Вывод печатается в указанный <file> если задан.

--help-policies [<file>]

Вывести руководство cmake-policies и выйти.

Руководство cmake-policies(7) выводится в удобочитаемом текстовом формате. Вывод печатается в указанный <file> если задан.

--help-property <prop> [<file>]

Вывести справку по одному свойству и выйти.

Записи справочника cmake-properties(7) для <prop> выводятся в удобочитаемом текстовом формате. Вывод печатается в указанный <file> если задан.

--help-property-list [<file>]

Вывести список свойств со справкой и выйти.

Список содержит все свойства, для которых справку можно получить, используя параметр --help-property вместе с именем свойства. Вывод печатается в указанный <file> если задан.

--help-properties [<file>]

Печать руководства cmake-properties и выход.

Руководство cmake-properties(7) печатается в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

--help-variable <var> [<file>]

Печать справки по одной переменной и выход.

Запись справки cmake-variables(7) для <var> печатается в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

--help-variable-list [<file>]

Список переменных со доступной справкой и выход.

Список содержит все переменные, для которых справка может быть получена с помощью опции --help-variable и последующим именем переменной. Вывод печатается в указанный <file> файл, если он задан.

--help-variables [<file>]

Печать руководства cmake-variables и выход.

Руководство cmake-variables(7) печатается в удобочитаемом текстовом формате. Вывод печатается в указанный <file> файл, если он задан.

Соответствие меток

Тесты могут иметь прикреплённые к ним метки. Тесты могут быть включены или исключены из выполнения теста путём фильтрации по меткам. Каждый отдельный фильтр — это регулярное выражение, применяемое к меткам, прикреплённым к тесту.

Когда используется -L, для того, чтобы тест был включён в выполнение теста, каждое регулярное выражение должно соответствовать по крайней мере одной метке. Использование более одной опции -L означает «совпадение всех этих».

Опция -LE работает так же, как -L, но исключает тесты, а не включает их. Тест исключается, если каждое регулярное выражение соответствует по крайней мере одной метке.

Если у теста нет прикреплённых к нему меток, то -L никогда не включит этот тест, а -LE никогда не исключит его. В качестве примера тестов с метками рассмотрим пять тестов со следующими метками:

• test1 имеет метки tuesday и production
• test2 имеет метки tuesday и test
• test3 имеет метки wednesday и production
• test4 имеет метку wednesday
• test5 имеет метки friday и test

Запуск ctest с -L tuesday -L test выберет test2, который имеет обе метки. Запуск CTest с -L test выберет test2 и test5, потому что оба они имеют метку, соответствующую этому регулярному выражению.

Поскольку сопоставление выполняется с помощью регулярных выражений, обратите внимание, что запуск CTest с -L es будет соответствовать всем пяти тестам. Для выбора тестов tuesday и wednesday вместе используйте одно регулярное выражение, которое соответствует любому из них, например -L "tue|wed".

Сводка меток и подпроектов

CTest печатает сводку временных характеристик для каждого LABEL и подпроекта, связанного с запущенными тестами. Сводка времени по меткам не будет включать метки, сопоставленные с подпроектами.

Когда свойство теста PROCESSORS установлено, CTest отобразит взвешенный результат времени выполнения теста в сводках по меткам и подпроектам. Время указывается с помощью sec*proc вместо простого sec.

Взвешенная сводка времени, представленная для каждой метки или подпроекта j вычисляется следующим образом:

Weighted Time Summary for Label/Subproject j =
    sum(raw_test_time[j,i] * num_processors[j,i], i=1...num_tests[j])

for labels/subprojects j=1...total

где:

• raw_test_time[j,i]: Время настенных часов для i теста для метки или подпроекта j
• num_processors[j,i]: Значение свойства CTest PROCESSORS для i теста для метки или подпроекта j
• num_tests[j]: Количество тестов, связанных с меткой или подпроектом j
• total: Общее количество меток или подпроектов, имеющих по крайней мере один запущенный тест

Следовательно, взвешенная сводка времени для каждой метки или подпроекта представляет собой количество времени, которое CTest потратил на выполнение тестов для каждой метки или подпроекта, и даёт хорошее представление о суммарных затратах тестов для каждой метки или подпроекта по сравнению с другими метками или подпроектами.

Например, если SubprojectA показал 100 sec*proc и SubprojectB показал 10 sec*proc, то CTest выделил примерно в 10 раз больше времени процессора/ядра для выполнения тестов для SubprojectA по сравнению с SubprojectB (например, если будут затрачены усилия на уменьшение стоимости набора тестов для всего проекта, то уменьшение стоимости набора тестов для SubprojectA, вероятно, окажет большее влияние, чем усилия по уменьшению стоимости набора тестов для SubprojectB).

Режим сборки и тестирования

CTest предоставляет командную строку для настройки (т. е. запуска cmake), сборки и/или выполнения теста:

ctest --build-and-test <path-to-source> <path-to-build>
      --build-generator <generator>
      [<options>...]
      [--build-options <opts>...]
      [--test-command <command> [<args>...]]

Шаги конфигурации и тестирования являются необязательными. Аргументы этой командной строки — каталоги исходных и бинарных файлов. Опция --build-generator должна быть указана для использования --build-and-test. Если указан --test-command, он будет запущен после завершения сборки. Другие опции, которые влияют на этот режим, включают:

--build-and-test

Переключение в режим сборки и тестирования.

--build-target

Указывает конкретную цель для сборки. Опция может быть указана несколько раз с различными целями, в этом случае каждая цель собирается по очереди. Очистка будет выполнена перед сборкой каждой цели, если не указана опция --build-noclean.

Если не указана --build-target, собирается цель all.

--build-nocmake

Выполнение сборки без предварительного запуска cmake.

Пропуск шага cmake.

--build-run-dir

Указывает каталог для запуска программ.

Каталог, в котором будут находиться программы после компиляции.

--build-two-config

Запуск CMake дважды.

--build-exe-dir

Указывает каталог для исполняемого файла.

--build-generator

Указывает генератор для использования. См. руководство cmake-generators(7).

--build-generator-platform

Указывает платформу, специфичную для генератора.

--build-generator-toolset

Указывает набор инструментов, специфичный для генератора.

--build-project

Указывает имя проекта для сборки.

--build-makeprogram

Указывает явную программу make, которая будет использоваться CMake при настройке и сборке проекта. Применимо только для генераторов на основе Make и Ninja.

--build-noclean

Пропустить шаг очистки make.

--build-config-sample

Пример исполняемого файла для определения конфигурации, которая должна быть использована. Например, Debug, Release и т. д.

--build-options

Дополнительные параметры для настройки сборки (т. е. для CMake, а не для инструмента сборки). Обратите внимание, что если это указано, ключевое слово --build-options и его аргументы должны быть последними параметрами, заданными в командной строке, за исключением возможного случая --test-command.

--test-command

Команда для запуска в качестве шага тестирования с опцией --build-and-test. Все аргументы, следующие за этим ключевым словом, будут считаться частью командной строки теста, поэтому она должна быть последней заданной опцией.

--test-timeout

Предел времени в секундах.

Клиент панели управления

CTest может работать как клиент для приложения панели управления качеством программного обеспечения CDash. Как клиент панели управления CTest выполняет последовательность шагов для настройки, сборки и тестирования программного обеспечения, а затем отправляет результаты на сервер CDash. Командная строка, используемая для отправки в CDash, имеет вид:

ctest -D <dashboard>         [-- <dashboard-options>...]
ctest -M <model> -T <action> [-- <dashboard-options>...]
ctest -S <script>            [-- <dashboard-options>...]
ctest -SP <script>           [-- <dashboard-options>...]

Варианты для клиента панели мониторинга включают:

-D <dashboard>, --dashboard <dashboard>

Выполнить тест панели мониторинга.

Этот параметр сообщает CTest действовать как клиенту CDash и выполнить тест панели мониторинга. Все тесты <Mode><Test>, где <Mode> может быть Experimental, Nightly, и Continuous, а <Test> может быть Start, Update, Configure, Build, Test, Coverage, и Submit.

Если <dashboard> не является одним из распознанных <Mode><Test> значений, это будет рассматриваться как определение переменной вместо этого (см. dashboard-options ниже).

-M <model>, --test-model <model>

Устанавливает модель для панели мониторинга.

Этот параметр сообщает CTest действовать как клиенту CDash, где <model> может быть Experimental, Nightly, и Continuous. Объединение -M и -T аналогично -D.

-T <action>, --test-action <action>

Устанавливает действие панели мониторинга.

Этот параметр сообщает CTest действовать как клиенту CDash и выполнить какое-либо действие, такое как start, build, test и т. д. Полный список действий см. в разделе Шаги клиента панели мониторинга. Объединение -M и -T аналогично -D.

-S <script>, --script <script>

Выполнить панель мониторинга для конфигурации.

Этот параметр сообщает CTest загрузить скрипт конфигурации, который задаёт ряд параметров, таких как двоичные и исходные каталоги. Затем CTest выполнит необходимые действия для создания и запуска панели мониторинга. Этот параметр в основном настраивает панель мониторинга и затем выполняет ctest -D с соответствующими параметрами.

-SP <script>, --script-new-process <script>

Выполнить панель мониторинга для конфигурации.

Этот параметр выполняет те же операции, что и -S, но выполнит их в отдельном процессе. Это в первую очередь полезно в тех случаях, когда скрипт может изменить среду, и вы не хотите, чтобы изменённая среда влияла на другие скрипты -S.

Доступные <dashboard-options> следующие:

-D <var>:<type>=<value>

Определить переменную для режима сценария.

Передать значения переменных в командной строке. Использовать вместе с -S для передачи значений переменных в скрипт панели мониторинга. Разбор -D аргументов в качестве значений переменных будет осуществлен только в том случае, если значение, следующее за -D, не соответствует ни одному из известных типов панелей мониторинга.

--group <group>

Укажите, в какую группу вы хотите отправить результаты

Отправить панель мониторинга в указанную группу вместо стандартной. По умолчанию панель мониторинга отправляется в группу Nightly, Experimental или Continuous, но с помощью этого параметра группа может быть произвольной.

Заменяет устаревший параметр --track. Несмотря на смену названия, его поведение не изменилось.

-A <file>, --add-notes <file>

Добавить файл заметок при отправке.

Этот параметр сообщает CTest включить файл заметок при отправке панели мониторинга.

--tomorrow-tag

Nightly или Experimental начинается с тега следующего дня.

Это полезно, если сборка не завершится в течение одного дня.

--extra-submit <file>[;<file>]

Отправить дополнительные файлы на панель мониторинга.

Этот параметр позволит отправить дополнительные файлы на панель мониторинга.

--http-header <header>

Новое в версии 3.29.

Добавить HTTP-заголовок при отправке на панель мониторинга.

Этот параметр заставит CTest добавить указанный заголовок при отправке на панель мониторинга. Этот параметр можно указывать несколько раз.

--http1.0

Отправить с помощью HTTP 1.0.

Этот параметр заставит CTest использовать HTTP 1.0 для отправки файлов на панель мониторинга вместо HTTP 1.1.

--no-compress-output

Не сжимать выходные данные тестов при отправке.

Этот флаг отключит автоматическое сжатие выходных данных тестов. Используйте его для сохранения совместимости со старой версией CDash, которая не поддерживает сжатые выходные данные тестов.

Шаги клиента панели мониторинга

CTest определяет упорядоченный список этапов тестирования, некоторые или все из которых могут быть выполнены как клиент панели мониторинга:

Start

Начать новую отправку на панель мониторинга, которая будет состоять из результатов, записанных в следующих шагах. См. раздел Шаг запуска CTest ниже.

Update

Обновить исходное дерево из его репозитория системы управления версиями. Записать старые и новые версии и список обновлённых исходных файлов. См. раздел Шаг обновления CTest ниже.

Configure

Настроить программное обеспечение, выполнив команду в дереве сборки. Записать журнал вывода конфигурации. См. раздел Шаг конфигурации CTest ниже.

Build

Собрать программное обеспечение, выполнив команду в дереве сборки. Записать журнал вывода сборки и определить предупреждения и ошибки. См. раздел Шаг сборки CTest ниже.

Test

Протестировать программное обеспечение, загрузив CTestTestfile.cmake из дерева сборки и выполнив определённые тесты. Записать вывод и результат каждого теста. См. раздел Шаг тестирования CTest ниже.

Coverage

Вычислить охват исходного кода, выполнив инструмент анализа охвата и записав его вывод. См. раздел Шаг охвата CTest ниже.

MemCheck

Запустить программный тест-набор через инструмент проверки памяти. Записать выходные данные тестов, результаты и проблемы, обнаруженные инструментом. См. раздел Шаг CTest MemCheck ниже.

Submit

Отправить результаты, записанные из других этапов тестирования, на сервер панели мониторинга качества программного обеспечения. См. раздел Шаг отправки CTest ниже.

Режимы клиента панели мониторинга

CTest определяет три режима работы в качестве клиента панели мониторинга:

Nightly

Этот режим предназначен для вызова один раз в день, обычно ночью. Он по умолчанию включает шаги Start, Update, Configure, Build, Test, Coverage, и Submit. Выбранные шаги выполняются даже если шаг Update не обнаруживает изменений в исходном дереве.

Continuous

Этот режим предназначен для вызова многократно в течение дня. Он по умолчанию включает шаги Start, Update, Configure, Build, Test, Coverage, и Submit, но завершается после шага Update если он не обнаруживает изменений в исходном дереве.

Experimental

Этот режим предназначен для вызова разработчиком для тестирования локальных изменений. Он по умолчанию включает шаги Start, Configure, Build, Test, Coverage, и Submit.

Клиент панели мониторинга через командную строку CTest

CTest может выполнять тестирование на уже сгенерированном дереве сборки. Запустите команду ctest с текущим рабочим каталогом, установленным в дереве сборки, и используйте одну из этих подписей:

ctest -D <mode>[<step>]
ctest -M <mode> [-T <step>]...

<mode> должен быть одним из вышеперечисленных Режимов клиента панели мониторинга, а каждый <step> должен быть одним из вышеперечисленных Шагов клиента панели мониторинга.

CTest считывает параметры конфигурации клиента панели мониторинга из файла в дереве сборки под названием CTestConfiguration.ini или DartConfiguration.tcl (названия являются историческими). Формат файла:

# Lines starting in '#' are comments.
# Other non-blank lines are key-value pairs.
<setting>: <value>

где <setting> — имя параметра, а <value> — значение параметра.

В деревьях сборки, сгенерированных CMake, этот файл конфигурации генерируется модулем CTest, если он включён в проект. Модуль использует переменные для получения значения каждого параметра, как документировано ниже.

Клиент панели мониторинга через скрипт CTest

CTest может выполнять тестирование, управляемое скриптом cmake-language(7), который создаёт и поддерживает исходное и дерево сборки, а также выполняет этапы тестирования. Запустите команду ctest с текущим рабочим каталогом вне любого дерева сборки и используйте одну из этих подписей:

ctest -S <script>
ctest -SP <script>

Файл <script> должен вызывать команды Команды CTest, чтобы явно выполнить шаги тестирования, как документировано ниже. Команды получают настройки конфигурации клиента панели управления из своих аргументов или из переменных, установленных в скрипте.

Конфигурация клиента панели управления

Шаги клиента панели управления Шаги клиента панели управления могут быть сконфигурированы с помощью именованных настроек, как документировано в следующих разделах.

Шаг CTest Start

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

В Скрипте CTest команда ctest_start() выполняет этот шаг. Аргументы команды могут указать некоторые настройки шага. Команда сначала выполняет команду, указанную в командной строке переменной CTEST_CHECKOUT_COMMAND, если она установлена, чтобы инициализировать каталог исходных файлов.

Настройки конфигурации включают:

BuildDirectory

Полный путь к дереву сборки проекта.

• Переменная скрипта CTest Script: CTEST_BINARY_DIRECTORY
• Переменная модуля CTest: PROJECT_BINARY_DIR

SourceDirectory

Полный путь к дереву исходных файлов проекта.

• Переменная скрипта CTest Script: CTEST_SOURCE_DIRECTORY
• Переменная модуля CTest: PROJECT_SOURCE_DIR

Шаг CTest Update

В Скрипте CTest команда ctest_update() выполняет этот шаг. Аргументы команды могут указать некоторые настройки шага.

Настройки конфигурации для указания инструмента системы управления версиями включают:

BZRCommand

bzr инструмент командной строки, используемый, если дерево исходного кода управляется Bazaar.

• Скрипт CTest переменная: CTEST_BZR_COMMAND
• CTest переменная модуля: none

BZRUpdateOptions

Параметры командной строки для BZRCommand при обновлении исходного кода.

• Скрипт CTest переменная: CTEST_BZR_UPDATE_OPTIONS
• CTest переменная модуля: none

CVSCommand

cvs инструмент командной строки, используемый, если дерево исходного кода управляется CVS.

• Скрипт CTest переменная: CTEST_CVS_COMMAND
• CTest переменная модуля: CVSCOMMAND

CVSUpdateOptions

Параметры командной строки для CVSCommand при обновлении исходного кода.

• Скрипт CTest переменная: CTEST_CVS_UPDATE_OPTIONS
• CTest переменная модуля: CVS_UPDATE_OPTIONS

GITCommand

git инструмент командной строки, используемый, если дерево исходного кода управляется Git.

• Скрипт CTest переменная: CTEST_GIT_COMMAND
• CTest переменная модуля: GITCOMMAND

Дерево исходного кода обновляется с помощью git fetch, за которым следует git reset --hard в FETCH_HEAD. Результат такой же, как у git pull, за исключением того, что любые локальные изменения перезаписываются. Используйте GITUpdateCustom для указания другого подхода.

GITInitSubmodules

Если установлено, CTest обновит подмодули репозитория перед обновлением.

• Скрипт CTest переменная: CTEST_GIT_INIT_SUBMODULES
• CTest переменная модуля: CTEST_GIT_INIT_SUBMODULES

GITUpdateCustom

Укажите пользовательскую командную строку (в виде списка, разделённого точкой с запятой) для выполнения в дереве исходного кода (рабочей области Git) для его обновления вместо запуска GITCommand.

• Скрипт CTest переменная: CTEST_GIT_UPDATE_CUSTOM
• CTest переменная модуля: CTEST_GIT_UPDATE_CUSTOM

GITUpdateOptions

Параметры командной строки для GITCommand при обновлении исходного кода.

• Скрипт CTest переменная: CTEST_GIT_UPDATE_OPTIONS
• CTest переменная модуля: GIT_UPDATE_OPTIONS

HGCommand

hg инструмент командной строки, используемый, если дерево исходного кода управляется Mercurial.

• Скрипт CTest переменная: CTEST_HG_COMMAND
• CTest переменная модуля: none

HGUpdateOptions

Параметры командной строки для HGCommand при обновлении исходного кода.

• Скрипт CTest переменная: CTEST_HG_UPDATE_OPTIONS
• CTest переменная модуля: none

P4Client

Значение параметра -c для P4Command.

• Скрипт CTest переменная: CTEST_P4_CLIENT
• CTest переменная модуля: CTEST_P4_CLIENT

P4Command

p4 инструмент командной строки, используемый, если дерево исходного кода управляется Perforce.

• Скрипт CTest переменная: CTEST_P4_COMMAND
• CTest переменная модуля: P4COMMAND

P4Options

Параметры командной строки для P4Command для всех вызовов.

• Скрипт CTest переменная: CTEST_P4_OPTIONS
• CTest переменная модуля: CTEST_P4_OPTIONS

P4UpdateCustom

Укажите пользовательскую командную строку (в виде списка, разделённого точкой с запятой) для выполнения в дереве исходного кода (дереве Perforce) для его обновления вместо запуска P4Command.

• Скрипт CTest переменная: none
• CTest переменная модуля: CTEST_P4_UPDATE_CUSTOM

P4UpdateOptions

Параметры командной строки для P4Command при обновлении исходного кода.

• Скрипт CTest переменная: CTEST_P4_UPDATE_OPTIONS
• CTest переменная модуля: CTEST_P4_UPDATE_OPTIONS

SVNCommand

svn инструмент командной строки, используемый, если дерево исходного кода управляется Subversion.

• Скрипт CTest переменная: CTEST_SVN_COMMAND
• CTest переменная модуля: SVNCOMMAND

SVNOptions

Параметры командной строки для SVNCommand для всех вызовов.

• Скрипт CTest переменная: CTEST_SVN_OPTIONS
• CTest переменная модуля: CTEST_SVN_OPTIONS

SVNUpdateOptions

Параметры командной строки для SVNCommand при обновлении исходного кода.

• Скрипт CTest переменная: CTEST_SVN_UPDATE_OPTIONS
• CTest переменная модуля: SVN_UPDATE_OPTIONS

UpdateCommand

Укажите инструмент командной строки для управления системой контроля версий, не определяя VCS, который управляет деревом исходного кода.

• Скрипт CTest переменная: CTEST_UPDATE_COMMAND
• CTest модульная переменная: <VCS>COMMAND когда UPDATE_TYPE равен <vcs>, иначе UPDATE_COMMAND

UpdateOptions

Опции командной строки для UpdateCommand.

• Скрипт CTest переменная: CTEST_UPDATE_OPTIONS
• CTest модульная переменная: <VCS>_UPDATE_OPTIONS когда UPDATE_TYPE равен <vcs>, иначе UPDATE_OPTIONS

UpdateType

Укажите систему контроля версий, которая управляет деревом исходного кода, если её нельзя автоматически определить. Значение может быть bzr, cvs, git, hg, p4, или svn.

• Скрипт CTest переменная: нет, определено из дерева исходного кода
• CTest модульная переменная: UPDATE_TYPE если установлено, иначе CTEST_UPDATE_TYPE

UpdateVersionOnly

Укажите, что вы хотите, чтобы команда обновления системы контроля версий только обнаруживала текущую версию, которая взята из ветки, а не обновлялась до другой версии.

• Скрипт CTest переменная: CTEST_UPDATE_VERSION_ONLY

UpdateVersionOverride

Укажите текущую версию вашего дерева исходного кода.

Когда эта переменная установлена в строку отличную от пустой, CTest сообщит значение, которое вы указали, а не будет использовать команду обновления для обнаружения текущей версии, взятой из ветки. Использование этой переменной заменяет UpdateVersionOnly. Как и UpdateVersionOnly, использование этой переменной говорит CTest не обновлять дерево исходного кода до другой версии.

• Скрипт CTest переменная: CTEST_UPDATE_VERSION_OVERRIDE

Дополнительные параметры настройки включают:

NightlyStartTime

В режиме панели Nightly укажите "время начала ночных тестов". В централизованных системах контроля версий (cvs и svn) шаг Update извлекает версию программного обеспечения по состоянию на это время, чтобы несколько клиентов выбрали общую версию для тестирования. Это не определено в распределенных системах контроля версий, поэтому настройка игнорируется.

• Скрипт CTest переменная: CTEST_NIGHTLY_START_TIME
• CTest модульная переменная: NIGHTLY_START_TIME если установлено, иначе CTEST_NIGHTLY_START_TIME

Шаг конфигурации CTest

В скрипте CTest команда ctest_configure() выполняет этот шаг. Аргументы к команде могут указать некоторые из настроек шага.

Настройки конфигурации включают:

ConfigureCommand

Командная строка для запуска процесса конфигурации программного обеспечения. Она будет выполнена в расположении, указанном настройкой BuildDirectory.

• Скрипт CTest переменная: CTEST_CONFIGURE_COMMAND
• CTest модульная переменная: CMAKE_COMMAND за которым следует PROJECT_SOURCE_DIR

LabelsForSubprojects

Укажите список меток, разделённых точкой с запятой, которые будут обрабатываться как подпроекты. Это отображение будет передано в CDash при отправке результатов конфигурации, тестирования или сборки.

• Скрипт CTest переменная: CTEST_LABELS_FOR_SUBPROJECTS
• CTest модульная переменная: CTEST_LABELS_FOR_SUBPROJECTS

См. Сводку по меткам и подпроектам.

Шаг сборки CTest

В скрипте CTest команда ctest_build() выполняет этот шаг. Аргументы к команде могут указать некоторые из настроек шага.

Настройки конфигурации включают:

DefaultCTestConfigurationType

Когда система сборки позволяет выбирать конфигурацию во время сборки (например, Debug, Release), это определяет конфигурацию по умолчанию, которая будет собираться, если не задан параметр -C команде ctest. Значение будет подставлено в значение MakeCommand, заменив строку ${CTEST_CONFIGURATION_TYPE}, если она появляется.

• Скрипт CTest переменная: CTEST_CONFIGURATION_TYPE
• CTest модульная переменная: DEFAULT_CTEST_CONFIGURATION_TYPE, инициализируется переменной среды CMAKE_CONFIG_TYPE

LabelsForSubprojects

Укажите список меток, разделённых точкой с запятой, которые будут обрабатываться как подпроекты. Это отображение будет передано в CDash при отправке результатов конфигурации, тестирования или сборки.

• Скрипт CTest переменная: CTEST_LABELS_FOR_SUBPROJECTS
• CTest модульная переменная: CTEST_LABELS_FOR_SUBPROJECTS

См. Сводку по меткам и подпроектам.

MakeCommand

Командная строка для запуска процесса сборки программного обеспечения. Она будет выполнена в расположении, указанном настройкой BuildDirectory.

• Скрипт CTest переменная: CTEST_BUILD_COMMAND
• CTest модульная переменная: MAKECOMMAND, инициализируется командой build_command()

UseLaunchers

Для деревьев сборки, сгенерированных CMake с использованием одного из генераторов Makefile или Ninja генератора, укажите, включена ли функция CTEST_USE_LAUNCHERS модулем CTestUseLaunchers (также включён модулем CTest). При включении, сгенерированная система сборки обернёт каждый вызов компилятора, компоновщика или произвольной командной строки "запускателем", который общается с CTest через переменные среды и файлы для отчёта о подробных предупреждениях и ошибках сборки. Иначе, CTest должен "извлечь" данные диагностики из журнала вывода сборки.

• Скрипт CTest переменная: CTEST_USE_LAUNCHERS
• CTest модульная переменная: CTEST_USE_LAUNCHERS

Шаг тестирования CTest

В скрипте CTest, команда ctest_test() выполняет этот шаг. Аргументы команды могут задавать некоторые параметры шага.

Настройки конфигурации включают:

ResourceSpecFile

Укажите файл спецификации ресурсов файл спецификации ресурсов.

• Переменная скрипта CTest: CTEST_RESOURCE_SPEC_FILE
• Переменная модуля CTest: CTEST_RESOURCE_SPEC_FILE

Дополнительную информацию см. в разделе Распределение ресурсов.

LabelsForSubprojects

Укажите список меток, разделённых точкой с запятой, которые будут обрабатываться как подпроекты. Это отображение будет передано в CDash при отправке результатов конфигурации, тестирования или сборки.

• Переменная скрипта CTest: CTEST_LABELS_FOR_SUBPROJECTS
• Переменная модуля CTest: CTEST_LABELS_FOR_SUBPROJECTS

См. Резюме меток и подпроектов.

TestLoad

При одновременном запуске тестов (например, с помощью -j), постарайтесь не запускать тесты, которые могут привести к превышению заданного порога загрузки процессора.

• Переменная скрипта CTest: CTEST_TEST_LOAD
• Переменная модуля CTest: CTEST_TEST_LOAD

TimeOut

Укажите значение таймаута для каждого теста, если оно не указано в свойстве теста TIMEOUT или флаге --timeout.

• Переменная скрипта CTest: CTEST_TEST_TIMEOUT
• Переменная модуля CTest: DART_TESTING_TIMEOUT

Чтобы отправить дополнительные значения тестов в CDash, см. Дополнительные измерения тестов.

Шаг CTest Coverage

В скрипте CTest, команда ctest_coverage() выполняет этот шаг. Аргументы команды могут задавать некоторые параметры шага.

Настройки конфигурации включают:

CoverageCommand

Утилита командной строки для выполнения анализа покрытия программного обеспечения. Она будет выполнена в расположении, указанном настройкой BuildDirectory.

• Переменная скрипта CTest: CTEST_COVERAGE_COMMAND
• Переменная модуля CTest: COVERAGE_COMMAND

CoverageExtraFlags

Укажите параметры командной строки для утилиты CoverageCommand.

• Переменная скрипта CTest: CTEST_COVERAGE_EXTRA_FLAGS
• Переменная модуля CTest: COVERAGE_EXTRA_FLAGS

Эти параметры — первые аргументы, передаваемые утилите CoverageCommand.

Шаг CTest MemCheck

В скрипте CTest, команда ctest_memcheck() выполняет этот шаг. Аргументы команды могут задавать некоторые параметры шага.

Настройки конфигурации включают:

MemoryCheckCommand

Утилита командной строки для выполнения динамического анализа. Команды тестов будут запускаться через эту утилиту.

• Переменная скрипта CTest: CTEST_MEMORYCHECK_COMMAND
• Переменная модуля CTest: MEMORYCHECK_COMMAND

MemoryCheckCommandOptions

Укажите параметры командной строки для утилиты MemoryCheckCommand. Они будут размещены перед командной строкой теста.

• Переменная скрипта CTest: CTEST_MEMORYCHECK_COMMAND_OPTIONS
• Переменная модуля CTest: MEMORYCHECK_COMMAND_OPTIONS

MemoryCheckType

Укажите тип проверки памяти для выполнения.

• Переменная скрипта CTest: CTEST_MEMORYCHECK_TYPE
• Переменная модуля CTest: MEMORYCHECK_TYPE

MemoryCheckSanitizerOptions

Укажите параметры для санитайзеров при запуске со сборкой, включенной санитизация.

• Переменная скрипта CTest: CTEST_MEMORYCHECK_SANITIZER_OPTIONS
• Переменная модуля CTest: MEMORYCHECK_SANITIZER_OPTIONS

MemoryCheckSuppressionFile

Укажите файл, содержащий правила подавления для утилиты MemoryCheckCommand. Он будет передан с параметрами, соответствующими утилите.

• Переменная скрипта CTest: CTEST_MEMORYCHECK_SUPPRESSIONS_FILE
• Переменная модуля CTest: MEMORYCHECK_SUPPRESSIONS_FILE

Дополнительные настройки конфигурации включают:

BoundsCheckerCommand

Укажите MemoryCheckCommand, известный как совместимый с командной строкой Bounds Checker.

• CTest Script переменная: none
• CTest переменная модуля: none

PurifyCommand

Укажите MemoryCheckCommand, известный как совместимый с командной строкой Purify.

• CTest Script переменная: none
• CTest переменная модуля: PURIFYCOMMAND

ValgrindCommand

Укажите MemoryCheckCommand, известный как совместимый с командной строкой Valgrind.

• CTest Script переменная: none
• CTest переменная модуля: VALGRIND_COMMAND

ValgrindCommandOptions

Укажите опции командной строки для инструмента ValgrindCommand. Они будут размещены перед командной строкой теста.

• CTest Script переменная: none
• CTest переменная модуля: VALGRIND_COMMAND_OPTIONS

DrMemoryCommand

Укажите MemoryCheckCommand, известный как совместимый с командной строкой DrMemory.

• CTest Script переменная: none
• CTest переменная модуля: DRMEMORY_COMMAND

DrMemoryCommandOptions

Укажите опции командной строки для инструмента DrMemoryCommand. Они будут размещены перед командной строкой теста.

• CTest Script переменная: none
• CTest переменная модуля: DRMEMORY_COMMAND_OPTIONS

CudaSanitizerCommand

Укажите MemoryCheckCommand, известный как совместимый с командной строкой cuda-memcheck или compute-sanitizer.

• CTest Script переменная: none
• CTest переменная модуля: CUDA_SANITIZER_COMMAND

CudaSanitizerCommandOptions

Укажите опции командной строки для инструмента CudaSanitizerCommand. Они будут размещены перед командной строкой теста.

• CTest Script переменная: none
• CTest переменная модуля: CUDA_SANITIZER_COMMAND_OPTIONS

Шаг отправки CTest

В CTest Script, команда ctest_submit() выполняет этот шаг. Аргументы к команде могут указать некоторые настройки шага.

Настройки конфигурации включают:

BuildName

Опишите платформу клиента панели мониторинга коротким текстом. (Операционная система, компилятор и т. д.)

• Скрипт CTest переменная: CTEST_BUILD_NAME
• CTest модульная переменная: BUILDNAME

CDashVersion

Запись устаревшего варианта. Не используется.

• Скрипт CTest переменная: нет, обнаружено из сервера
• CTest модульная переменная: CTEST_CDASH_VERSION

CTestSubmitRetryCount

Укажите количество попыток повторной отправки при сбоях сети.

• Скрипт CTest переменная: нет, используйте опцию ctest_submit() RETRY_COUNT.
• CTest модульная переменная: CTEST_SUBMIT_RETRY_COUNT

CTestSubmitRetryDelay

Укажите задержку перед повторной отправкой при сбоях сети.

• Скрипт CTest переменная: нет, используйте опцию ctest_submit() RETRY_DELAY.
• CTest модульная переменная: CTEST_SUBMIT_RETRY_DELAY

CurlOptions

Укажите список опций, разделённых точкой с запятой, для управления библиотекой Curl, которую CTest использует для подключения к серверу. Возможные опции — CURLOPT_SSL_VERIFYPEER_OFF и CURLOPT_SSL_VERIFYHOST_OFF.

• Скрипт CTest переменная: CTEST_CURL_OPTIONS
• CTest модульная переменная: CTEST_CURL_OPTIONS

DropLocation

Устаревшая опция. Если SubmitURL не задано, оно строится из DropMethod, DropSiteUser, DropSitePassword, DropSite, и DropLocation.

• Скрипт CTest переменная: CTEST_DROP_LOCATION
• CTest модульная переменная: DROP_LOCATION если задано, иначе CTEST_DROP_LOCATION

DropMethod

Устаревшая опция. Если SubmitURL не задано, оно строится из DropMethod, DropSiteUser, DropSitePassword, DropSite, и DropLocation.

• Скрипт CTest переменная: CTEST_DROP_METHOD
• CTest модульная переменная: DROP_METHOD если задано, иначе CTEST_DROP_METHOD

DropSite

Устаревшая опция. Если SubmitURL не задано, оно строится из DropMethod, DropSiteUser, DropSitePassword, DropSite, и DropLocation.

• Скрипт CTest переменная: CTEST_DROP_SITE
• CTest модульная переменная: DROP_SITE если задано, иначе CTEST_DROP_SITE

DropSitePassword

Устаревшая опция. Если SubmitURL не задано, оно строится из DropMethod, DropSiteUser, DropSitePassword, DropSite, и DropLocation.

• Скрипт CTest переменная: CTEST_DROP_SITE_PASSWORD
• CTest модульная переменная: DROP_SITE_PASSWORD если задано, иначе CTEST_DROP_SITE_PASWORD

DropSiteUser

Устаревшая опция. Если SubmitURL не задано, оно строится из DropMethod, DropSiteUser, DropSitePassword, DropSite, и DropLocation.

• Скрипт CTest переменная: CTEST_DROP_SITE_USER
• CTest модульная переменная: DROP_SITE_USER если задано, иначе CTEST_DROP_SITE_USER

IsCDash

Устаревшая опция. Не используется.

• Скрипт CTest переменная: CTEST_DROP_SITE_CDASH
• CTest модульная переменная: CTEST_DROP_SITE_CDASH

ScpCommand

Устаревшая опция. Не используется.

• Скрипт CTest переменная: CTEST_SCP_COMMAND
• CTest модульная переменная: SCPCOMMAND

Site

Опишите сайт хоста клиента панели мониторинга коротким текстом. (Имя хоста, домен и т. д.)

• Скрипт CTest переменная: CTEST_SITE
• CTest модульная переменная: SITE, инициализирована командой site_name()

SubmitURL

URL сервера панели мониторинга (http или https) для отправки данных.

• Скрипт CTest переменная: CTEST_SUBMIT_URL
• CTest модульная переменная: SUBMIT_URL если задано, иначе CTEST_SUBMIT_URL

SubmitInactivityTimeout

Время ожидания отправки, после которого она отменяется, если не завершена. Укажите ноль для отключения таймаута.

• Скрипт CTest переменная: CTEST_SUBMIT_INACTIVITY_TIMEOUT
• CTest модульная переменная: CTEST_SUBMIT_INACTIVITY_TIMEOUT

TriggerSite

Устаревшая опция. Не используется.

• Скрипт CTest переменная: CTEST_TRIGGER_SITE
• CTest модульная переменная: TRIGGER_SITE если задано, иначе CTEST_TRIGGER_SITE

Отображение как JSON Объектная Модель

Когда предоставляется параметр командной строки --show-only=json-v1, информация о тесте выводится в формате JSON. Версия 1.0 модели JSON-объекта определена следующим образом:

kind

Строка "ctestInfo".

version

Объект JSON, определяющий компоненты версии. Его члены:

major

Целое неотрицательное число, задающее главный компонент версии.

minor

Целое неотрицательное число, задающее дополнительный компонент версии.

backtraceGraph

Объект JSON, представляющий информацию о стеке вызовов с указанными ниже членами:

commands

Список имён команд.

files

Список имён файлов.

nodes

Список узлов в виде объектов JSON с членами:

command

Индекс в члене commands объекта backtraceGraph.

file

Индекс в члене files объекта backtraceGraph.

line

Номер строки в файле, где был добавлен элемент стека вызовов.

parent

Индекс в члене nodes объекта backtraceGraph, представляющий родительский элемент в графе.

tests

Массив JSON, перечисляющий информацию о каждом тесте. Каждый элемент — это объект JSON с членами:

name

Название теста.

config

Конфигурация, на которой может выполняться тест. Пустая строка означает любую конфигурацию.

command

Список, где первый элемент — команда теста, а остальные — аргументы команды.

backtrace

Индекс в члене nodes объекта backtraceGraph.

properties

Свойства теста. Может содержать ключи для каждого из поддерживаемых свойств теста.

Распределение ресурсов

CTest предоставляет механизм для тестов, чтобы точно указывать необходимые ресурсы, а также для пользователей, чтобы указывать доступные ресурсы на исполняемой машине. Это позволяет CTest отслеживать, какие ресурсы используются, а какие свободны, планируя тесты таким образом, чтобы они не пытались использовать недоступные ресурсы.

При использовании функции распределения ресурсов CTest не будет перераспределять ресурсы. Например, если у ресурса 8 слотов, CTest не будет запускать тесты, которые вместе используют более 8 слотов одновременно. Это ограничивает количество тестов, которые могут запускаться одновременно, даже если используется высокое значение аргумента -j, если эти тесты все используют некоторые слоты одного и того же ресурса. Кроме того, это означает, что отдельный тест, использующий больше ресурсов, чем доступно на машине, вообще не запустится (и будет сообщено об ошибке Not Run).

Типичный случай использования этой функции — тесты, требующие использования графического процессора (GPU). Несколько тестов могут одновременно выделять память из GPU, но если слишком много тестов пытаются сделать это одновременно, некоторые из них не смогут выделить память, что приведёт к ошибке теста, даже если бы тест завершился успешно, имея необходимую память. С помощью функции распределения ресурсов каждый тест может указать, сколько памяти ему нужно из GPU, что позволяет CTest планировать тесты таким образом, чтобы одновременный запуск нескольких таких тестов не исчерпал пул памяти GPU.

Обратите внимание, что CTest не знает, что такое GPU или сколько памяти у него есть. У него нет возможности взаимодействовать с GPU для получения этой информации или выполнения каких-либо операций управления памятью, хотя проект может определить тест, предоставляющий данные о тестовой машине (см. Динамически генерируемый файл спецификации ресурсов).

CTest отслеживает список абстрактных типов ресурсов, каждый из которых имеет определённое количество слотов, доступных для использования тестами. Каждый тест указывает количество слотов, которые ему необходимы от определённого ресурса, и CTest планирует их так, чтобы общее количество используемых слотов не превышало указанную ёмкость. Когда тест выполняется и слоты от ресурса выделяются этому тесту, тесты могут предполагать, что они имеют исключительное использование этих слотов на всё время процесса теста.

Функция распределения ресурсов CTest состоит как минимум из двух входных данных:

• Файл спецификации ресурсов файл спецификации ресурсов, описанный ниже, который описывает доступные ресурсы в системе.
• Свойство RESOURCE_GROUPS тестов, которое описывает ресурсы, необходимые тесту.

Когда CTest выполняет тест, выделенные ресурсы передаются в виде набора переменных среды, как описано ниже. Определение, какой ресурс подключить, предоставляется автору теста.

Свойство RESOURCE_GROUPS сообщает CTest, какие ресурсы ожидается использовать тестом, сгруппированные таким образом, что это имеет смысл для теста. Сам тест должен прочитать переменные среды чтобы определить, какие ресурсы были выделены для каждой группы. Например, каждая группа может соответствовать процессу, который тест запустит при выполнении.

Обратите внимание, что даже если тест указывает свойство RESOURCE_GROUPS, он всё равно может быть выполнен без распределения ресурсов (и без соответствующих переменных среды) если пользователь не передаёт файл спецификации ресурсов. Передача этого файла, либо через аргумент командной строки --resource-spec-file, либо аргумент RESOURCE_SPEC_FILE к ctest_test(), активирует функцию распределения ресурсов. Тесты должны проверить переменную среды CTEST_RESOURCE_GROUP_COUNT, чтобы узнать, активировано ли распределение ресурсов. Эта переменная всегда (и только) определена, если активировано распределение ресурсов. Если распределение ресурсов не активировано, переменная CTEST_RESOURCE_GROUP_COUNT не будет существовать, даже если она существует для родительского процесса ctest. Если тесту абсолютно необходимо распределение ресурсов, он может вернуть код ошибки или использовать свойства SKIP_RETURN_CODE или SKIP_REGULAR_EXPRESSION для обозначения пропущенного теста.

Файл спецификации ресурсов

Файл спецификации ресурсов — это файл JSON, который передаётся CTest несколькими способами. Он может быть указан в командной строке с помощью опции ctest --resource-spec-file, он может быть передан в качестве аргумента RESOURCE_SPEC_FILE к ctest_test(), или он может быть динамически сгенерирован во время выполнения теста (см. Динамически генерируемый файл спецификации ресурсов).

Если используется скрипт панели мониторинга и RESOURCE_SPEC_FILE не указан, используется значение CTEST_RESOURCE_SPEC_FILE в скрипте панели мониторинга. Если --resource-spec-file, RESOURCE_SPEC_FILE, и CTEST_RESOURCE_SPEC_FILE в скрипте панели мониторинга не указаны, используется значение CTEST_RESOURCE_SPEC_FILE из CMake build. Если ничто из этого не указано, файл спецификации ресурсов не используется.

Файл спецификации ресурсов должен быть объектом JSON. Все примеры в этом документе предполагают следующий файл спецификации ресурсов:

{
  "version": {
    "major": 1,
    "minor": 0
  },
  "local": [
    {
      "gpus": [
        {
          "id": "0",
          "slots": 2
        },
        {
          "id": "1",
          "slots": 4
        },
        {
          "id": "2",
          "slots": 2
        },
        {
          "id": "3"
        }
      ],
      "crypto_chips": [
        {
          "id": "card0",
          "slots": 4
        }
      ]
    }
  ]
}

Члены:

version

Объект, содержащий поле major целого типа и поле minor целого типа. В настоящее время поддерживается только версия с главным номером 1, а второстепенный номер 0. Любое другое значение является ошибкой.

local

JSON-массив наборов ресурсов, присутствующих в системе. В настоящее время этот массив ограничен размером 1.

Каждый элемент массива — JSON-объект с членами, имена которых соответствуют требуемым типам ресурсов, например, gpus. Эти имена должны начинаться с маленькой буквы или символа подчёркивания, а последующие символы могут быть маленькими буквами, цифрами или символом подчёркивания. Заглавные буквы недопустимы, поскольку некоторые платформы имеют регистронезависимые переменные окружения. Более подробную информацию см. в разделе «Переменные окружения» ниже. Рекомендуется, чтобы имя типа ресурса было множественным числом от существительного, например, gpus или crypto_chips (а не gpu или crypto_chip).

Обратите внимание, что имена gpus и crypto_chips являются просто примерами, и CTest их никоим образом не интерпретирует. Вы можете придумать любые типы ресурсов, которые вам необходимы.

Значение для каждого типа ресурса — JSON-массив, состоящий из JSON-объектов, каждый из которых описывает конкретный экземпляр указанного ресурса. Эти объекты имеют следующие члены:

id

Строка, состоящая из идентификатора ресурса. Каждый символ в идентификаторе может быть маленькой буквой, цифрой или символом подчёркивания. Заглавные буквы недопустимы.

Идентификаторы должны быть уникальными внутри типа ресурса. Однако они не обязаны быть уникальными по всем типам ресурсов. Например, допустимо иметь ресурс gpus с именем 0 и ресурс crypto_chips с именем 0, но не два ресурса gpus с одинаковым именем 0.

Обратите внимание, что идентификаторы 0, 1, 2, 3 и card0 являются всего лишь примерами, и CTest их не интерпретирует. Вы можете придумать любые идентификаторы, которые вам необходимы.

slots

Необязательное целое число без знака, определяющее количество доступных слотов на ресурсе. Например, это может быть количество мегабайтов ОЗУ на видеокарте или количество криптографических блоков, доступных на криптографическом чипе. Если slots не указано, используется значение по умолчанию 1.

В приведённом выше примере присутствуют четыре видеокарты с идентификаторами от 0 до 3. Видеокарта 0 имеет 2 слота, видеокарта 1 — 4, видеокарта 2 — 2, а у видеокарты 3 количество слотов равно значению по умолчанию (1). Также есть один криптографический чип с 4 слотами.

RESOURCE_GROUPS Свойство

См. RESOURCE_GROUPS для описания этого свойства.

Переменные окружения

После того, как CTest определил, какие ресурсы следует выделить для теста, он передает эту информацию исполняемому файлу теста в виде ряда переменных окружения. Для каждого примера ниже мы будем предполагать, что у данного теста есть свойство RESOURCE_GROUPS со значением 2,gpus:2;gpus:4,gpus:1,crypto_chips:2.

Тестовому процессу передаются следующие переменные:

CTEST_RESOURCE_GROUP_COUNT

Общее количество групп, указанных в свойстве RESOURCE_GROUPS. Например:

• CTEST_RESOURCE_GROUP_COUNT=3

Эта переменная будет определена только в том случае, если ctest(1) был задан с --resource-spec-file, или если ctest_test() был задан с RESOURCE_SPEC_FILE. Если файл спецификаций ресурсов не указан, эта переменная не будет определена.

CTEST_RESOURCE_GROUP_<num>

Список типов ресурсов, выделенных каждой группе, при этом каждый элемент разделен запятой. <num> — число от нуля до CTEST_RESOURCE_GROUP_COUNT минус один. CTEST_RESOURCE_GROUP_<num> определено для каждого <num> в этом диапазоне. Например:

• CTEST_RESOURCE_GROUP_0=gpus
• CTEST_RESOURCE_GROUP_1=gpus
• CTEST_RESOURCE_GROUP_2=crypto_chips,gpus

CTEST_RESOURCE_GROUP_<num>_<resource-type>

Список идентификаторов ресурсов и количества слотов каждого идентификатора, выделенных каждой группе для данного типа ресурса. Эта переменная состоит из набора пар, каждая пара разделена точкой с запятой, а два элемента в паре разделены запятой. Первый элемент каждой пары — id: и ID ресурса типа <resource-type>, а второй элемент — slots: и количество слотов от этого ресурса, выделенных данной группе. Например:

• CTEST_RESOURCE_GROUP_0_GPUS=id:0,slots:2
• CTEST_RESOURCE_GROUP_1_GPUS=id:2,slots:2
• CTEST_RESOURCE_GROUP_2_GPUS=id:1,slots:4;id:3,slots:1
• CTEST_RESOURCE_GROUP_2_CRYPTO_CHIPS=id:card0,slots:2

В этом примере группа 0 получает 2 слота с видеокарты 0, группа 1 получает 2 слота с видеокарты 2, а группа 2 получает 4 слота с видеокарты 1, 1 слот с видеокарты 3 и 2 слота с криптографического чипа card0.

<num> — число от нуля до CTEST_RESOURCE_GROUP_COUNT минус один. <resource-type> — имя типа ресурса, преобразованное в верхний регистр. CTEST_RESOURCE_GROUP_<num>_<resource-type> определено для каждого из <num> в указанном диапазоне и каждого типа ресурса, указанного в CTEST_RESOURCE_GROUP_<num>.

Поскольку на некоторых платформах имена переменных окружения регистронезависимы, имена типов ресурсов могут не конфликтовать в регистронезависимой среде. По этой причине для простоты все типы ресурсов должны быть перечислены в нижнем регистре в файле спецификации ресурсов и в свойстве RESOURCE_GROUPS и преобразуются в верхний регистр в переменной окружения CTEST_RESOURCE_GROUP_<num>_<resource-type>.

Динамически создаваемый файл спецификаций ресурсов

Проект может необязательно указать один тест, который будет использоваться для динамического создания файла спецификаций ресурсов, который CTest будет использовать для планирования тестов, использующих ресурсы. Тест, генерирующий файл, должен иметь свойство GENERATED_RESOURCE_SPEC_FILE, и в свойстве FIXTURES_SETUP должно быть ровно одно фикстура. Эта фикстура считается CTest специальной: это фикстура, генерирующая файл спецификаций ресурсов. Фикстура может иметь любое имя. Если такая фикстура существует, все тесты, у которых установлено свойство RESOURCE_GROUPS, должны включать эту фикстуру в свойство FIXTURES_REQUIRED, и файл спецификаций ресурсов не может быть указан с аргументом --resource-spec-file или переменной CTEST_RESOURCE_SPEC_FILE.

Интеграция с сервером задач

В системах POSIX при выполнении в контексте сервера задач CTest разделяет свои слоты задач. Это независимо от свойства теста PROCESSORS, которое по-прежнему учитывается CTest в уровне параллельности -j. CTest получает ровно один токен от сервера задач перед запуском каждого теста и возвращает его после завершения теста.

Например, рассмотрим Makefile:

test:
	+ctest -j 8

При вызове с помощью make -j 2 test, ctest подключается к серверу задач, получает токен для каждого теста и запускает не более 2 тестов одновременно.

В системах Windows интеграция с сервером задач пока не реализована.

См. также

Ниже представлены ресурсы, которые помогут при использовании CMake:

Главная страница

https://cmake.org

Основная отправная точка для изучения CMake.

Онлайн-документация и ресурсы сообщества

https://cmake.org/documentation

На этой веб-странице содержатся ссылки на доступную документацию и ресурсы сообщества.

Форум Discourse

https://discourse.cmake.org

Форум Discourse предоставляет возможность обсуждения и задавать вопросы о CMake.