ctest(1)

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

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

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

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

  • Шаг CTest Start
  • Шаг CTest Update
  • Шаг CTest Configure
  • Шаг CTest Build
  • Шаг CTest Test
  • Шаг CTest Coverage
  • Шаг CTest MemCheck
  • Шаг CTest Submit
• Показать как JSON-объектную модель

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

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

Синтаксис

ctest [<options>]
ctest --build-and-test <path-to-source> <path-to-build>
      --build-generator <generator> [<options>...]
      [--build-options <opts>...] [--test-command <command> [<args>...]]
ctest {-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>}
      [-- <dashboard-options>...]

Описание

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

Параметры

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

-F

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

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

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

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

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

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

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

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

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

human

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

json-v1

Вывести информацию о тесте в формате JSON. См. Модель отображения в формате JSON.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Выполнить тест панели управления.

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

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

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

Определение переменной для режима сценария.

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

-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 скрипты.

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

-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 запускать тесты в интерактивном или неинтерактивном режиме. В Windows это означает, что в неинтерактивном режиме все всплывающие окна отладки системы блокируются. В режиме панели мониторинга (Experimental, Nightly, Continuous ) по умолчанию используется неинтерактивный режим. При простом запуске тестов, не предназначенных для панели мониторинга, по умолчанию разрешается отображение всплывающих окон и интерактивная отладка.

--no-label-summary

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

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

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

--no-subproject-summary

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

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

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

--build-and-test См. Режим сборки и тестирования.

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

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

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

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

--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=<[error|ignore]>

Считать отсутствие тестов либо ошибкой, либо игнорировать её.

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

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

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

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

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

Показать баннер с именем/версией программы и выйти.

Если файл указан, версия записывается в него. Помощь выводится в указанный файл <f>, если он задан.

--help-full [<f>]

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

Все руководства выводятся в удобочитаемом текстовом формате. Помощь выводится в указанный файл <f>, если он задан.

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

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

Указанное руководство выводится в удобочитаемом текстовом формате. Помощь выводится в указанный файл <f>, если он задан.

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

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

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

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

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

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

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

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

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

--help-commands [<f>]

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

Руководство cmake-commands(7) выводится в удобочитаемом текстовом формате. Помощь выводится в указанный файл <f>, если он задан.

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

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

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

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

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

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

--help-modules [<f>]

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

Руководство cmake-modules(7) выводится в удобочитаемом текстовом формате. Помощь выводится в указанный файл <f>, если он задан.

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

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

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

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

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

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

--help-policies [<f>]

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

Руководство cmake-policies(7) выводится в удобочитаемом текстовом формате. Помощь выводится в указанный файл <f>, если он задан.

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

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

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

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

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

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

--help-properties [<f>]

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

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

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

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

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

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

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

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

--help-variables [<f>]

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

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

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

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 раз больше времени CPU/ядра потратил на выполнение тестов для 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-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 clean.

--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> | -M <model> -T <action> | -S <script> | -SP <script>)
      [-- <dashboard-options>...]

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

--group <group>

Указывает группу, в которую необходимо отправить результаты

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

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

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

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

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

--tomorrow-tag

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

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

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

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

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

--http1.0

Отправить с использованием HTTP 1.0.

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

--no-compress-output

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

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

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

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

Start

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

Update

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

Configure

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

Build

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

Test

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

Coverage

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

MemCheck

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

Submit

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

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

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

Nightly

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

Continuous

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

Experimental

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

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

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

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

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

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

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

где <setting> — имя настройки, а <value> — значение настройки.

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

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

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

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

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

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

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

Шаг запуска CTest

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

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

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

BuildDirectory

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

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

SourceDirectory

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

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

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

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

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

BZRCommand

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

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

BZRUpdateOptions

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

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

CVSCommand

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

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

CVSUpdateOptions

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

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

GITCommand

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

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

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

GITInitSubmodules

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

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

GITUpdateCustom

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

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

GITUpdateOptions

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

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

HGCommand

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

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

HGUpdateOptions

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

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

P4Client

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

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

P4Command

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

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

P4Options

Командные параметры для P4Command для всех вызовов.

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

P4UpdateCustom

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

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

P4UpdateOptions

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

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

SVNCommand

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

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

SVNOptions

Командные параметры для SVNCommand для всех вызовов.

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

SVNUpdateOptions

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

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

UpdateCommand

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

• Скрипт 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), это задаёт конфигурацию по умолчанию, которая будет собираться, если к команде ctest не указан параметр -C. Значение будет подставлено в значение 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

Укажите файл спецификации ресурсов. Более подробная информация приведена в разделе Распределение ресурсов.

LabelsForSubprojects

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

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

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

TestLoad

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

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

TimeOut

Таймаут по умолчанию для каждого теста, если не указан свойством теста TIMEOUT.

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

Шаг покрытия 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

Шаг 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

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

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

DropLocation

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

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

DropMethod

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

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

DropSite

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

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

DropSitePassword

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

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

DropSiteUser

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

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

IsCDash

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

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

ScpCommand

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

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

Site

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

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

SubmitURL

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

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

TriggerSite

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

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

Отобразить в формате JSON объекта

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

kind

Строка “ctestInfo”.

version

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

major

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

minor

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

backtraceGraph

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

commands

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

files

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

nodes

Список узлов в формате JSON с членами:

command

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

file

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

line

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

parent

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

tests

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

name

Имя теста.

config

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

command

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

backtrace

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

properties

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

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

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

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

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

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

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

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

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

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

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

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

Файл спецификации ресурсов — это файл JSON, передаваемый в CTest, либо через командную строку ctest(1) в виде --resource-spec-file, либо в качестве аргумента RESOURCE_SPEC_FILE команды ctest_test(). Файл спецификации ресурсов должен быть объектом 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 типа integer. В настоящее время поддерживается только версия 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 слота с видеокарты 0, группе 1 — 2 слота с видеокарты 2, группе 2 — 4 слота с видеокарты 1, 1 слот с видеокарты 3, и 2 слота с криптографического чипа card0.

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

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

См. также

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

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

https://cmake.org

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

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

https://cmake.org/documentation

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

Форум Discourse

https://discourse.cmake.org

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