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

并行运行测试，可以选择限制为给定的并行级别。

在版本 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 选项结合使用时非常有用。

3.14 版本中新增： --show-only 选项接受 <format> 值。

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

human
用户友好的输出。这不能保证稳定。这是默认值。

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

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

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

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

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

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

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

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

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

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

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

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

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

--tests-from-file <filename>¶

3.29 版本中新增。

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

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

--exclude-from-file <filename>¶

3.29 版本中新增。

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

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

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

从自动将任何测试添加到测试集中排除与 <regex> 匹配的夹具。

如果要执行的测试集中某个测试需要特定的夹具，则通常会自动将该夹具的设置和清理测试添加到测试集中。此选项阻止为与 <regex> 匹配的夹具添加设置或清理测试。请注意，所有其他夹具行为都将保留，包括测试依赖项和跳过设置测试失败的测试。

-FS <regex>, --fixture-exclude-setup <regex>¶: 与 -FA 相同，只是排除了匹配的设置测试。

-FC <regex>, --fixture-exclude-cleanup <regex>¶: 与 -FA 相同，只是排除了匹配的清理测试。

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

按编号运行特定数量的测试。

此选项使 CTest 从编号 Start 开始运行测试，到编号 End 结束，并以 Stride 为增量。Stride 后面的任何其他数字都被视为单个测试编号。Start、End 或 Stride 可以为空。可以选择提供一个文件，其中包含与命令行相同的语法。

-U, --union¶

获取 -I 和 -R 的并集。

当 -R 和 -I 都被指定时，默认情况下会运行测试的交集。通过指定 -U，将改为运行测试的并集。

--rerun-failed¶

仅运行之前失败的测试。

此选项指示 CTest 仅执行其先前运行期间失败的测试。当指定此选项时，CTest 会忽略所有其他旨在修改要运行的测试列表的选项（-L、-R、-E、-LE、-I 等）。如果 CTest 运行且没有测试失败，则随后使用 --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 被设置。

在 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 环境变量来设置。

查看帮助 ¶

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

-version [<file>], --version [<file>], /V [<file>]¶: 显示程序名称/版本标语并退出。如果给出，则输出将打印到名为 <file> 的文件中。

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

打印使用信息并退出。

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

打印一个命令的帮助信息并退出。

以人类可读的文本格式打印 <cmd> 的 cmake-commands(7) 手册条目。如果给出，则输出将打印到名为 <file> 的文件中。

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

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

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

--help-commands [<file>]¶

打印 cmake-commands 手册并退出。

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

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

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

以人类可读的文本格式打印 <mod> 的 cmake-modules(7) 手册条目。如果给出，则输出将打印到名为 <file> 的文件中。

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

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

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

--help-modules [<file>]¶

打印 cmake-modules 手册并退出。

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

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

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

以人类可读的文本格式打印 <cmp> 的 cmake-policies(7) 手册条目。如果给出，则输出将打印到名为 <file> 的文件中。

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

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

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

--help-policies [<file>]¶

打印 cmake-policies 手册并退出。

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

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

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

以人类可读的文本格式打印 <prop> 的 cmake-properties(7) 手册条目。如果给出，则输出将打印到名为 <file> 的文件中。

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

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

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

--help-properties [<file>]¶

打印 cmake-properties 手册并退出。

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

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

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

以易于阅读的文本格式打印 <var> 在 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 和子项目打印计时摘要信息。标签时间摘要将不包括映射到子项目的标签。

3.22版本中新增：在测试执行期间动态添加的标签也会在计时摘要中报告。请参阅其他标签。

当设置 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 分配的 CPU/核心时间大约是运行 SubprojectA 测试的 10 倍，而不是运行 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>]¶

将额外文件提交到仪表盘。

此选项会将额外文件提交到仪表盘。

--http-header <header>¶

3.29 版本中新增。

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

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

--http1.0¶

使用HTTP 1.0提交。

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

--no-compress-output¶

提交时不压缩测试输出。

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

仪表盘客户端步骤 ¶

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

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

仪表盘客户端模式 ¶

CTest 将仪表盘客户端的运行模式定义为三种。

夜间: 此模式旨在每天调用一次，通常在夜间。默认情况下，它启用 Start、Update、Configure、Build、Test、Coverage 和 Submit 步骤。即使 Update 步骤报告源代码树没有更改，也会运行选定的步骤。
持续: 此模式旨在在一天中的任何时间重复调用。默认情况下，它启用 Start、Update、Configure、Build、Test、Coverage 和 Submit 步骤，但如果 Update 步骤报告源代码树没有更改，则在 Update 步骤后退出。
实验: 此模式旨在由开发人员调用以测试本地更改。默认情况下，它启用 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 变量（如果已设置）指定的命令行，以初始化源目录。

配置设置包括

构建目录

项目构建树的完整路径。

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

源代码目录

项目源代码树的完整路径。

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

CTest 更新步骤 ¶

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

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

BZR 命令

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

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

BZR 更新选项

更新源代码时 BZRCommand 的命令行选项。

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

CVS 命令

如果源代码树由 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

更新类型

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

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

仅更新版本

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

CTest 脚本变量：CTEST_UPDATE_VERSION_ONLY

覆盖更新版本

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

当此变量设置为非空字符串时，CTest 将报告您指定的 value，而不是使用更新命令来发现当前签出的版本。使用此变量会取代 UpdateVersionOnly。与 UpdateVersionOnly 类似，使用此变量告诉 CTest 不要将源代码树更新到其他版本。

CTest 脚本变量：CTEST_UPDATE_VERSION_OVERRIDE

其他配置设置包括

夜间开始时间

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

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

CTest 配置步骤 ¶

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

配置设置包括

配置命令

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

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

子项目的标签

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

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

参见标签和子项目摘要。

CTest 构建步骤 ¶

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

配置设置包括

默认 CTest 配置类型

当要启动的构建系统允许在构建时选择配置（例如 Debug、Release）时，这指定了在 -C 选项未传递给 ctest 命令时要构建的默认配置。如果 MakeCommand 的值中出现文字字符串 ${CTEST_CONFIGURATION_TYPE}，则该值将替换它。

CTest 脚本变量：CTEST_CONFIGURATION_TYPE
CTest 模块变量：DEFAULT_CTEST_CONFIGURATION_TYPE，由 CMAKE_CONFIG_TYPE 环境变量初始化

子项目的标签

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

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

参见标签和子项目摘要。

构建命令

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

CTest 脚本变量：CTEST_BUILD_COMMAND
CTest 模块变量：MAKECOMMAND，由 build_command() 命令初始化

使用启动器

对于使用 Makefile 生成器或 Ninja 生成器由 CMake 生成的构建树，指定 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

更多信息请参见资源分配。

子项目的标签

指定一个用分号分隔的标签列表，这些标签将被视为子项目。此映射将在提交配置、测试或构建结果时传递给 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

使用启用消毒的构建运行时，指定消毒程序的选项。

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