ctest(1)

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

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

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

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

  • Шаг CTest Start
  • Шаг CTest Update
  • Шаг CTest Configure
  • Шаг CTest Build
  • Шаг CTest Test
  • Шаг CTest Coverage
  • Шаг CTest MemCheck
  • Шаг CTest Submit
• Отображение в виде модели JSON-объекта

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

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

Синопсис

Run Tests
 ctest [<options>]

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

Включить возможность восстановления.

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

-j <jobs>, --parallel <jobs>

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

Этот параметр указывает CTest на параллельное выполнение тестов с использованием заданного числа задач. Этот параметр также можно задать, задав переменную среды 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> в формате JUnit XML. Если <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). См. Сопоставление меток.

-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>

Указать каталог для поиска тестов.

--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-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>

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

Отправка панели мониторинга в указанную группу вместо стандартной. По умолчанию панель мониторинга отправляется в группу «Ежедневная», «Экспериментальная» или «Непрерывная», но при указании этого параметра группа может быть произвольной.

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

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

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

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

--tomorrow-tag

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

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

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

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

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

--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 ниже.

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

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

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

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

BuildDirectory

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

• Сценарий CTest переменная: CTEST_BINARY_DIRECTORY
• CTest модуль переменная: PROJECT_BINARY_DIR

SourceDirectory

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

• Сценарий CTest переменная: CTEST_SOURCE_DIRECTORY
• CTest модуль переменная: PROJECT_SOURCE_DIR

Шаг обновления CTest

В Сценарии 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.

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

Для отправки дополнительных значений тестов в CDash см. Дополнительные измерения тестов.

Шаг CTest Покрытия

В сценарии 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 переменная: none
• CTest модульная переменная: none

PurifyCommand

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

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

ValgrindCommand

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

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

ValgrindCommandOptions

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

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

DrMemoryCommand

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

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

DrMemoryCommandOptions

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

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

CudaSanitizerCommand

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

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

CudaSanitizerCommandOptions

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

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

Шаг CTest Submit

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

Параметры конфигурации включают:

BuildName

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

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

CDashVersion

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

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

CTestSubmitRetryCount

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

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

CTestSubmitRetryDelay

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

• Сценарий CTest переменная: none, используйте параметр 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: за которым следует идентификатор ресурса типа <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>.

См. также

Следующие ресурсы помогут вам в использовании CMake:

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

https://cmake.org

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

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

https://cmake.org/documentation

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

Форум Discourse

https://discourse.cmake.org

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

CDash: https://cdash.org