ctest(1)

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

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

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

• Настройка клиента панели управления

  • Шаг запуска CTest
  • Шаг обновления CTest
  • Шаг конфигурации CTest
  • Шаг сборки CTest
  • Шаг тестирования CTest
  • Шаг покрытия CTest
  • Шаг проверки памяти CTest
  • Шаг отправки CTest
• Показать как JSON-модель объекта

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

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

Синтаксис

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

Включить восстановление.

Эта опция позволяет 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-load <level>

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

Когда ctest выполняется как клиент панели управления, это устанавливает опцию TestLoad шага CTest Тестирования.

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

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

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

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 Script: CTEST_BINARY_DIRECTORY
• Переменная модуля CTest: PROJECT_BINARY_DIR

SourceDirectory

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

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

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

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

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

BZRCommand

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

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

BZRUpdateOptions

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

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

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 модульная переменная: не задано

HGUpdateOptions

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

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

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 переменная: не задано
• 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

Устарело начиная с версии 3.30: Используйте TLSVerify вместо этого.

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

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

Возможные опции:

CURLOPT_SSL_VERIFYPEER_OFF

Отключить опцию curl CURLOPT_SSL_VERIFYPEER.

CURLOPT_SSL_VERIFYHOST_OFF

Отключить опцию curl CURLOPT_SSL_VERIFYHOST.

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

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

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

TLSVersion

Добавлен в версии 3.30.

Укажите минимальную версию TLS, разрешенную при отправке на панель мониторинга через URL-адреса https://.

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

Изменено в версии 3.31: По умолчанию используется TLS 1.2. Ранее по умолчанию минимальная версия не навязывалась.

TLSVerify

Добавлен в версии 3.30.

Укажите булево значение, определяющее, нужно ли проверять сертификат сервера при отправке на панель управления через https:// URL-адреса.

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

Изменено в версии 3.31: По умолчанию включено. Ранее по умолчанию было выключено. Пользователи могут установить переменную окружения CMAKE_TLS_VERIFY в значение 0 для восстановления старого значения по умолчанию.

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, всё равно возможно его выполнение без распределения ресурсов (и без соответствующих переменных среды), если пользователь не передаёт файл спецификации ресурсов. Передача этого файла, либо через параметр командной строки ctest --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 сборки. Если ни один из них не указан, файл спецификации ресурсов не используется.

Файл спецификации ресурсов должен быть объектом 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 типа целое число. В настоящее время поддерживается только версия major 1, minor 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) был задан файл спецификации ресурсов или если ctest_test() был задан файл спецификации ресурсов. Если файл спецификации ресурсов не задан, эта переменная не будет определена.

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.