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

--test-load <level>

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

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

-Q, --quiet

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

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

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

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

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

--output-junit <file>

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

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

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

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

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

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

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

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

human

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

json-v1

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

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

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

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

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

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

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

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

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

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

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

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

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

--tests-from-file <filename>

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

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

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

--exclude-from-file <filename>

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

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

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

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

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

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

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

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

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

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

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

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

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

-U, --union

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

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

--rerun-failed

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

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

--repeat <mode>:<n>

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

until-fail

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

until-pass

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

after-timeout

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

--repeat-until-fail <n>

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

--max-width <width>

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

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

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

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

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

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

--no-label-summary

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

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

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

--no-subproject-summary

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

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

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

--test-dir <dir>

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

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

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

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

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

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

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

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

--test-output-truncation <mode>

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

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

--overwrite

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

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

--force-new-ctest-process

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

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

--schedule-random

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

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

--submit-index

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

--timeout <seconds>

Установить значение таймаута по умолчанию для тестов.

Этот параметр фактически устанавливает таймаут для всех тестов, у которых не задан таймаут через свойство TIMEOUT.

--stop-time <time>

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

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

--print-labels

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

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

--no-tests=<action>

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

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

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

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

View Help

Чтобы вывести подробности версии или выбранные страницы документации 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

Запустить набор тестов программного обеспечения через инструмент проверки памяти. Записать вывод теста, результаты и проблемы, обнаруженные инструментом. См. раздел Шаг 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 Script команда 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 Script команда 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 Configure

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

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

В скрипте 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

В скрипте 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 переменная: нет, определяется из сервера
• 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

Отключить параметр CURLOPT_SSL_VERIFYPEER curl.

CURLOPT_SSL_VERIFYHOST_OFF

Отключить параметр CURLOPT_SSL_VERIFYHOST curl.

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

http или https URL сервера панели мониторинга для отправки результатов.

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

SubmitInactivityTimeout

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

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

TLSVersion

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

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

• Сценарий 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). Несколько тестов могут одновременно выделять память из видеокарты, но если слишком много тестов попытаются сделать это одновременно, некоторые из них не смогут выделить память, что приведёт к ошибке теста, даже если бы тест завершился успешно, имея необходимую память. Используя функцию распределения ресурсов, каждый тест может указать, сколько памяти ему требуется из видеокарты, позволяя CTest планировать тесты таким образом, чтобы одновременный запуск нескольких таких тестов не исчерпал пул памяти видеокарты.

Обратите внимание, что CTest не имеет понятия о том, что такое видеокарта (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 целого типа. В настоящее время поддерживается только версия 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

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

В примере файла выше есть четыре GPU с ID от 0 до 3. GPU 0 имеет 2 слота, GPU 1 — 4, GPU 2 — 2, а GPU 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 слота с GPU 0, группа 1 получает 2 слота с GPU 2, а группа 2 получает 4 слота с GPU 1, 1 слот с GPU 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.