ctest(1)¶

概要 ¶

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 的测试驱动程序。对于使用 enable_testing() 和 add_test() 命令的项目，CMake 生成的构建树都具有测试支持。该程序将运行测试并报告结果。

运行测试 ¶

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

并行运行测试，可选择限制并行级别。

Added in version 3.29: 可以省略 <level>，或者设置为 0，在这种情况下：

在作业服务器集成下，并行度受可用作业令牌限制。
否则，如果省略该值，并行度受处理器数量限制，或者为 2，以较大者为准。
否则，如果值为 0，则并行度不受限制。

此选项也可以通过 CTEST_PARALLEL_LEVEL 环境变量指定。

此选项可与 PROCESSORS 测试属性一起使用。请参阅标签与子项目摘要。

--resource-spec-file <file>¶

在启用资源分配的情况下运行 CTest，使用 <file> 中指定的资源规范文件。

当 ctest 作为仪表盘客户端运行时，这会设置 CTest 测试步骤的 ResourceSpecFile 选项。

--test-load <level>¶

在并行运行测试时（例如使用 -j），尽量不要在 CPU 负载可能超过给定阈值时启动测试。

当 ctest 作为仪表盘客户端运行时，这会设置 CTest 测试步骤的 TestLoad 选项。

-Q, --quiet¶

使 CTest 安静运行。

此选项将禁止所有输出。如果指定了 --output-log，仍会生成输出日志文件。如果指定了 --quiet，诸如 --verbose、--extra-verbose 和 --debug 等选项将被忽略。

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

输出到日志文件。

此选项告诉 CTest 将其所有输出写入 <file> 日志文件。

--output-junit <file>¶

3.21 版本新增。

以 JUnit 格式写入测试结果。

此选项告诉 CTest 以 JUnit XML 格式将测试结果写入 <file>。如果 <file> 已经存在，它将被覆盖。如果使用 -S 选项运行仪表盘脚本，请改用 ctest_test() 命令的 OUTPUT_JUNIT 关键字。

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

禁止实际执行测试。

此选项告诉 CTest 列出将要运行的测试，但不要真正运行它们。与 -R 和 -E 选项结合使用时非常有用。

Added in version 3.14: --show-only 选项接受一个 <format> 值。

<format> 可以是以下值之一。

人工
人类可读输出。不保证其稳定性。这是默认值。

json-v1
以 JSON 格式导出测试信息。请参阅显示为 JSON 对象模型。

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

运行标签匹配正则表达式的测试，如 string(REGEX) 下所述。

此选项告诉 CTest 仅运行标签与给定正则表达式匹配的测试。当给出多个 -L 选项时，只有当每个正则表达式至少匹配测试的一个标签时，测试才会被运行（即多个 -L 标签形成 AND 关系）。请参阅标签匹配。

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

运行名称匹配正则表达式的测试。

此选项告诉 CTest 仅运行名称与给定正则表达式匹配的测试。

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

排除名称匹配正则表达式的测试。

此选项告诉 CTest 不要运行名称与给定正则表达式匹配的测试。

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

排除标签匹配正则表达式的测试。

此选项告诉 CTest 不要运行标签与给定正则表达式匹配的测试。当给出多个 -LE 选项时，只有当每个正则表达式至少匹配测试的一个标签时，测试才会被排除（即多个 -LE 标签形成 AND 关系）。请参阅标签匹配。

--tests-from-file <filename>¶

在版本 3.29 中添加。

运行给定文件中列出的测试。

此选项告诉 CTest 运行给定文件中列出的测试。该文件必须每行包含一个精确的测试名称。与任何测试名称不完全匹配的行将被忽略。此选项可以与 -R、-E、-L 或 -LE 等其他选项组合使用。

--exclude-from-file <filename>¶

在版本 3.29 中添加。

排除给定文件中列出的测试。

此选项告诉 CTest 不要运行给定文件中列出的测试。该文件必须每行包含一个精确的测试名称。与任何测试名称不完全匹配的行将被忽略。此选项可以与 -R、-E、-L 或 -LE 等其他选项组合使用。

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

从自动添加到测试集的测试中排除与 <regex> 匹配的夹具（fixture）。

如果待执行测试集中的某个测试需要特定的夹具，该夹具的设置（setup）和清理（cleanup）测试通常会自动添加到测试集中。此选项可防止添加与 <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 运行后没有测试失败，则后续带有 --rerun-failed 选项的 CTest 调用将运行最近一次失败的测试集（如果有）。

--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 被设置。

交互模式允许 Windows 错误报告 (WER) 显示调试弹出窗口并创建核心转储。要在测试中启用核心转储，请使用交互模式，并遵循 Windows 文档关于收集用户模式转储 (Collecting User-Mode Dumps) 的说明。

Changed in version 4.0: Windows 错误报告 (WER) 在交互模式下已启用，因此测试进程可能会显示调试弹出窗口并创建核心转储。这得益于 libuv 的更新。

Changed in version 3.11: Windows 错误报告 (WER) 在交互和非交互模式下均被禁用，因此测试进程不会显示弹出窗口或创建核心转储。这是由于使用 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 本身的测试的一项现已移除的优化。

--schedule-random¶

使用随机顺序进行测试调度。

此选项将以随机顺序运行测试。它通常用于检测测试套件中的隐式依赖关系。

--schedule-random-seed¶

在 4.1 版本中新增。

覆盖随机顺序种子。

此选项用于重现由于 --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 环境变量来设置。

--collect-instrumentation <build>¶: 4.0 版本新增。

手动从指定的构建目录收集指令数据。更多详细信息，请参阅 CMake 指令中的索引 (Indexing) 部分。

查看帮助 ¶

要打印版本详细信息或 CMake 文档中的选定页面，请使用以下选项之一

-version[=json-v1] [<file>], --version[=json-v1] [<file>], /V[=json-v1] [<file>], /version[=json-v1] [<file>]¶

显示程序名称/版本横幅并退出。如果指定了 json-v1，则以 JSON 格式打印扩展版本信息。JSON 输出包含 CMake 及其依赖项的版本。如果给定了 <file>，输出将被打印到该指定文件。

JSON 输出格式以机器可读的形式由 此 JSON 模式 描述。

-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) 手册条目以人类可读的文本格式打印。如果指定了 <file>，则输出将打印到该文件。

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

列出可获取帮助的命令并退出。

列表包含所有可以通过使用 `--help-command` 选项后跟命令名称来获取帮助的命令。如果指定了 <file>，则输出将打印到该文件。

--help-commands [<file>]¶

打印 cmake-commands 手册并退出。

cmake-commands(7) 手册以人类可读的文本格式打印。如果指定了 <file>，则输出将打印到该文件。

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

打印一个模块的帮助并退出。

cmake-modules(7) 手册条目以人类可读的文本格式打印。如果指定了 <file>，则输出将打印到该文件。

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

列出可获取帮助的模块并退出。

列表包含所有可以通过使用 `--help-module` 选项后跟模块名称来获取帮助的模块。如果指定了 <file>，则输出将打印到该文件。

--help-modules [<file>]¶

打印 cmake-modules 手册并退出。

cmake-modules(7) 手册以人类可读的文本格式打印。如果指定了 <file>，则输出将打印到该文件。

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

打印一个策略的帮助并退出。

cmake-policies(7) 手册条目以人类可读的文本格式打印。如果指定了 <file>，则输出将打印到该文件。

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

列出可获取帮助的策略并退出。

列表包含所有可以通过使用 `--help-policy` 选项后跟策略名称来获取帮助的策略。如果指定了 <file>，则输出将打印到该文件。

--help-policies [<file>]¶

打印 cmake-policies 手册并退出。

cmake-policies(7) 手册以人类可读的文本格式打印。如果指定了 <file>，则输出将打印到该文件。

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

打印一个属性的帮助并退出。

cmake-properties(7) 手册条目以人类可读的文本格式打印。如果指定了 <file>，则输出将打印到该文件。

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

列出可获取帮助的属性并退出。

列表包含所有可以通过使用 `--help-property` 选项后跟属性名称来获取帮助的属性。如果指定了 <file>，则输出将打印到该文件。

--help-properties [<file>]¶

打印 cmake-properties 手册并退出。

cmake-properties(7) 手册以人类可读的文本格式打印。如果指定了 <file>，则输出将打印到该文件。

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

打印一个变量的帮助并退出。

cmake-variables(7) 手册条目以人类可读的文本格式打印。如果指定了 <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

运行带有 -L tuesday -L test 的 ctest 将选择 test2，因为它具有这两个标签。运行带有 -L test 的 CTest 将选择 test2 和 test5，因为它们都具有一个与该正则表达式匹配的标签。

由于匹配是通过正则表达式进行的，请注意，运行带有 -L es 的 CTest 将匹配所有五个测试。要同时选择 tuesday 和 wednesday 测试，请使用匹配其中任何一个的单个正则表达式，例如 -L "tue|wed"。

标签与子项目摘要 ¶

CTest 会为每个 LABEL 和与所运行测试关联的子项目打印时间摘要信息。标签时间摘要将不包括映射到子项目的标签。

Added in version 3.22: 测试执行期间动态添加的标签也会在时间摘要中报告。请参阅其他标签 (Additional Labels)。

当设置了 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]：j 标签或子项目下第 i 个测试的挂钟时间。
num_processors[j,i]：j 标签或子项目下第 i 个测试的 CTest PROCESSORS 属性值。
num_tests[j]：与 j 标签或子项目关联的测试数量。
total：至少运行了一个测试的标签或子项目的总数。

因此，每个标签或子项目的加权时间摘要代表了 CTest 为运行该标签或子项目的测试所分配的时间量，并且在与其他标签或子项目进行比较时，很好地代表了这些测试的总开销。

例如，如果 SubprojectA 显示为 100 sec*proc 而 SubprojectB 显示为 10 sec*proc，那么 CTest 分配给运行 SubprojectA 的测试的 CPU/核心时间大约是 SubprojectB 的 10 倍（例如，如果要投入精力减少整个项目的测试套件成本，那么减少 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¶: 指定 CMake 在配置和构建项目时要使用的明确的 make 程序。仅适用于基于 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>         [-- <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> 值之一，它将被视为变量定义（请参阅下方的仪表盘选项）。

-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>]¶: 将额外的 .xml 部分文件提交给仪表盘。请参阅 ctest_submit() 命令的 PARTS ExtraFiles 选项。

--http-header <header>¶

在版本 3.29 中添加。

提交到仪表盘时附加 HTTP 头。

此选项将导致 CTest 在提交到仪表盘时附加指定的头。此选项可以多次指定。

--http1.0¶

使用 HTTP 1.0 进行提交。

此选项将强制 CTest 使用 HTTP 1.0 向仪表盘提交文件，而不是 HTTP 1.1。

--no-compress-output¶

提交时不要压缩测试输出。

此标志将关闭测试输出的自动压缩。使用此选项可保持与不支持压缩测试输出的旧版本 CDash 的兼容性。

仪表盘客户端步骤 ¶

CTest 定义了一个有序的测试步骤列表，其中部分或全部步骤可以作为仪表盘客户端运行：

Start（开始）: 启动一个新的仪表板提交，由以下步骤记录的结果组成。请参阅下方的 CTest 启动步骤部分。
更新 (Update): 从版本控制仓库更新源码树。记录旧版本、新版本以及更新后的源文件列表。请参阅下方的 CTest 更新步骤部分。
配置 (Configure): 通过在构建树中运行命令来配置软件。记录配置输出日志。请参阅下方的 CTest 配置步骤部分。
构建 (Build): 通过在构建树中运行命令来构建软件。记录构建输出日志，并检测警告和错误。请参阅下方的 CTest 构建步骤部分。
测试 (Test): 通过从构建树加载 CTestTestfile.cmake 并执行定义的测试来测试软件。记录每个测试的输出和结果。请参阅下方的 CTest 测试步骤部分。
覆盖率 (Coverage): 通过运行覆盖率分析工具并记录其输出来计算源代码的覆盖率。请参阅下方的 CTest 覆盖率步骤部分。
内存检查 (MemCheck): 通过内存检查工具运行软件测试套件。记录测试输出、结果以及该工具报告的问题。请参阅下方的 CTest 内存检查步骤部分。
提交 (Submit): 将其他测试步骤中记录的结果提交到软件质量仪表板服务器。请参阅下方的 CTest 提交步骤部分。

仪表板客户端模式 ¶

CTest 定义了作为仪表板客户端的三种操作模式

夜间模式 (Nightly): 此模式旨在每天调用一次，通常在夜间。默认情况下，它启用 Start、Update、Configure、Build、Test、Coverage 和 Submit 步骤。即使 Update 步骤报告源码树没有变更，所选步骤也会运行。
持续模式 (Continuous): 此模式旨在全天反复调用。默认情况下，它启用 Start、Update、Configure、Build、Test、Coverage 和 Submit 步骤，但如果 Update 步骤报告源码树没有变更，它会在该步骤后退出。
实验模式 (Experimental): 此模式旨在由开发人员调用以测试本地更改。默认情况下，它启用 Start、Configure、Build、Test、Coverage 和 Submit 步骤。

通过 CTest 命令行使用的仪表板客户端 ¶

CTest 可以在已生成的构建树上执行测试。在构建树目录中运行 ctest 命令，并使用以下签名之一

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

<mode> 必须是上述仪表板客户端模式之一，且每个 <step> 必须是上述仪表板客户端步骤之一。

CTest 从构建树中的 CTestConfiguration.ini 或 DartConfiguration.tcl（名称具有历史沿革）文件中读取仪表板客户端配置设置。该文件的格式为

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

其中 <setting> 是设置名称，<value> 是设置值。

在 CMake 生成的构建树中，此配置文件由 CTest 模块生成（如果项目包含了该模块）。该模块使用变量来获取每个设置的值，如下方的设置文档所述。

通过 CTest 脚本使用的仪表板客户端 ¶

CTest 可以通过 cmake-language(7) 脚本来执行测试，该脚本负责创建和维护源码树及构建树，并执行测试步骤。在任意构建树之外的当前工作目录中运行 ctest 命令，并使用以下签名之一

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

<script> 文件必须调用 CTest 命令来显式运行测试步骤（如下所述）。这些命令通过其参数或脚本中设置的变量来获取仪表板客户端配置设置。

仪表板客户端配置 ¶

仪表板客户端步骤可以通过下述各节中记录的命名设置进行配置。

CTest 启动步骤 ¶

启动一个新的仪表板提交，由后续步骤记录的结果组成。

在 CTest 脚本中，ctest_start() 命令用于运行此步骤。该命令的参数可以指定某些步骤设置。如果设置了 CTEST_CHECKOUT_COMMAND 变量，该命令会首先运行此变量指定的命令行，以初始化源码目录。

配置设置包括

BuildDirectory

项目构建树的完整路径。

CTest 脚本变量：CTEST_BINARY_DIRECTORY
CTest 模块变量：PROJECT_BINARY_DIR

SourceDirectory

项目源码树的完整路径。

CTest 脚本变量：CTEST_SOURCE_DIRECTORY
CTest 模块变量：PROJECT_SOURCE_DIR

CTest 更新步骤 ¶

在 CTest 脚本中，ctest_update() 命令用于运行此步骤。该命令的参数可以指定某些步骤设置。

用于指定版本控制工具的配置设置包括

BZRCommand

如果源码树由 Bazaar 管理，则使用此 bzr 命令行工具。

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

如果源码树由 Mercurial 管理，则使用此 hg 命令行工具。

CTest 脚本变量：CTEST_HG_COMMAND
CTest 模块变量：无

HGUpdateOptions

更新源码时传给 HGCommand 的命令行选项。

CTest 脚本变量：CTEST_HG_UPDATE_OPTIONS
CTest 模块变量：无

P4Client

P4Command 的 -c 选项的值。

CTest 脚本变量：CTEST_P4_CLIENT
CTest 模块变量：CTEST_P4_CLIENT

P4Command

如果源码树由 Perforce 管理，则使用此 p4 命令行工具。

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

如果源码树由 Subversion 管理，则使用此 svn 命令行工具。

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 模块变量：当 UPDATE_TYPE 为 <vcs> 时为 <VCS>COMMAND，否则为 UPDATE_COMMAND

UpdateOptions

传给 UpdateCommand 的命令行选项。

CTest 脚本变量：CTEST_UPDATE_OPTIONS
CTest 模块变量：当 UPDATE_TYPE 为 <vcs> 时为 <VCS>_UPDATE_OPTIONS，否则为 UPDATE_OPTIONS

UpdateType

如果无法自动检测，请指定管理源码树的版本控制系统。值可以是 bzr, cvs, git, hg, p4 或 svn。

CTest 脚本变量：无，从源码树检测
CTest 模块变量：如果已设置则为 UPDATE_TYPE，否则为 CTEST_UPDATE_TYPE

UpdateVersionOnly

指定您希望版本控制更新命令仅发现当前检出的版本，而不更新到不同的版本。

CTest 脚本变量：CTEST_UPDATE_VERSION_ONLY

UpdateVersionOverride

指定您的源码树的当前版本。

当此变量设置为非空字符串时，CTest 将报告您指定的值，而不是使用更新命令来发现当前检出的版本。使用此变量将覆盖 UpdateVersionOnly。与 UpdateVersionOnly 一样，使用此变量会告诉 CTest 不要将源码树更新到不同的版本。

CTest 脚本变量：CTEST_UPDATE_VERSION_OVERRIDE

其他配置设置包括

NightlyStartTime

在 Nightly 仪表板模式下，指定“夜间开始时间”。对于集中式版本控制系统（cvs 和 svn），Update 步骤会检出截至该时间的软件版本，以便多个客户端选择相同的版本进行测试。这在分布式版本控制系统中没有明确定义，因此该设置会被忽略。

CTest 脚本变量：CTEST_NIGHTLY_START_TIME
CTest 模块变量：如果已设置则为 NIGHTLY_START_TIME，否则为 CTEST_NIGHTLY_START_TIME

CTest 配置步骤 ¶

在 CTest 脚本中，ctest_configure() 命令用于运行此步骤。该命令的参数可以指定某些步骤设置。

配置设置包括

ConfigureCommand

用于启动软件配置过程的命令行。它将在 BuildDirectory 设置指定的位置执行。

CTest 脚本变量：CTEST_CONFIGURE_COMMAND
CTest 模块变量：CMAKE_COMMAND 后跟 PROJECT_SOURCE_DIR

LabelsForSubprojects

指定一个分号分隔的标签列表，这些标签将被视为子项目。当提交配置、测试或构建结果时，此映射将传递给 CDash。

CTest 脚本变量：CTEST_LABELS_FOR_SUBPROJECTS
CTest 模块变量：CTEST_LABELS_FOR_SUBPROJECTS

请参阅标签与子项目摘要。

CTest 构建步骤 ¶

在 CTest 脚本中，ctest_build() 命令用于运行此步骤。该命令的参数可以指定某些步骤设置。

配置设置包括

DefaultCTestConfigurationType

当启动的构建系统允许在构建时选择配置（例如 Debug, Release）时，此项指定当未向 ctest 命令提供 -C 选项时所构建的默认配置。如果字面字符串 ${CTEST_CONFIGURATION_TYPE} 出现在 MakeCommand 中，该值将被替换。

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 生成器生成的构建树，指定 CTestUseLaunchers 模块（也包含在 CTest 模块中）是否启用了 CTEST_USE_LAUNCHERS 功能。启用后，生成的构建系统会使用“启动器”包装编译器、链接器或自定义命令行的每次调用，该启动器通过环境变量和文件与 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），尽量不要在 CPU 负载可能超过给定阈值时启动测试。

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

在使用已启用清理程序 (sanitize) 的构建运行时，指定传给清理程序的选项。

CTest 脚本变量：CTEST_MEMORYCHECK_SANITIZER_OPTIONS
CTest 模块变量：MEMORYCHECK_SANITIZER_OPTIONS

MemoryCheckSuppressionFile

指定一个包含 MemoryCheckCommand 工具抑制规则的文件。它将连同适合该工具的选项一起传递。

CTest 脚本变量：CTEST_MEMORYCHECK_SUPPRESSIONS_FILE
CTest 模块变量：MEMORYCHECK_SUPPRESSIONS_FILE

其他配置设置包括

BoundsCheckerCommand

指定已知在命令行上与 Bounds Checker 兼容的 MemoryCheckCommand。

CTest 脚本变量：无
CTest 模块变量：无

PurifyCommand

指定已知在命令行上与 Purify 兼容的 MemoryCheckCommand。

CTest 脚本变量：无
CTest 模块变量：PURIFYCOMMAND

ValgrindCommand

指定已知在命令行上与 Valgrind 兼容的 MemoryCheckCommand。

CTest 脚本变量：无
CTest 模块变量：VALGRIND_COMMAND

ValgrindCommandOptions

指定传给 ValgrindCommand 工具的命令行选项。它们将被放置在测试命令行之前。

CTest 脚本变量：无
CTest 模块变量：VALGRIND_COMMAND_OPTIONS

DrMemoryCommand

指定已知在命令行上与 DrMemory 兼容的 MemoryCheckCommand。

CTest 脚本变量：无
CTest 模块变量：DRMEMORY_COMMAND

DrMemoryCommandOptions

指定传给 DrMemoryCommand 工具的命令行选项。它们将被放置在测试命令行之前。

CTest 脚本变量：无
CTest 模块变量：DRMEMORY_COMMAND_OPTIONS

CudaSanitizerCommand

指定已知在命令行上与 cuda-memcheck 或 compute-sanitizer 兼容的 MemoryCheckCommand。

CTest 脚本变量：无
CTest 模块变量：CUDA_SANITIZER_COMMAND

CudaSanitizerCommandOptions

指定传给 CudaSanitizerCommand 工具的命令行选项。它们将被放置在测试命令行之前。

CTest 脚本变量：无
CTest 模块变量：CUDA_SANITIZER_COMMAND_OPTIONS

CTest 提交步骤 ¶

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

指定一个分号分隔的选项列表，用于控制 CTest 内部用于连接服务器的 Curl 库。

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