构建工具开发工具CLI【免费下载链接】CMakeMirror of CMake upstream repository项目地址https://gitcode.com/gh_mirrors/cm/CMake点击查看免费下载本指南围绕 CMake 仓库中ctest_read_custom_files命令展开讲解如何在 CTest 脚本模式下手动加载CTestCustom.cmake/CTestCustom.ctest自定义配置文件剖析其底层文件搜索规则、默认行为与源码实现并结合仓库测试用例给出可复用的实战示例。读完本文你将掌握 CTest 自定义配置的加载机制并能自主编写、调试自定义 CTest 配置文件。命令概述在脚本模式中主动读取 CTestCustom 文件ctest_read_custom_files是 CTest 内置的脚本命令用于从指定目录读取 CTest 自定义配置文件。官方命令文档Help/command/ctest_read_custom_files.rst给出的定义非常简洁Read all theCTestCustom.ctestorCTestCustom.cmakefiles from the given directory.By default, invokingctest(1)without a script will read custom files from the binary directory.即该命令从给定目录读取CTestCustom.ctest或CTestCustom.cmake文件默认情况下不带脚本调用ctest(1)时会从二进制目录binary directory读取这些自定义文件。它的典型应用场景是在ctest -S script.cmake脚本模式CTest 脚本模式下当自定义配置文件不在默认的二进制目录、或者需要从多个位置加载配置时用该命令显式指定配置来源。命令语法与参数语义命令签名如下ctest_read_custom_files(directory...)directory...表示可以同时传入一个或多个目录参数命令会依次在每个目录中查找并读取自定义配置文件参数不能为空。源码 Source/CTest/cmCTestReadCustomFilesCommand.cxx 在InitialPass中首先检查if (args.empty()) { status.SetError(called with incorrect number of arguments); return false; }因此不带任何参数调用时会直接报错 called with incorrect number of arguments 并以失败状态返回。文件查找规则扩展名优先级与目录语义命令的实际文件查找逻辑位于 Source/cmCTest.cxx 的cmCTest::ReadCustomConfigurationFileTree方法中其核心行为如下auto const fname [this, dir]() - std::string { for (char const* ext : { .cmake, .ctest }) { std::string path cmStrCat(dir, /CTestCustom, ext); cmCTestLog(this, DEBUG, * Check for file: , path, \n); if (cmSystemTools::FileExists(path)) { return path; } } return ; }();从这段实现可以提炼出几条明确的规则文件名固定只查找名为CTestCustom的文件扩展名为.cmake或.ctest扩展名优先级按CTestCustom.cmake、CTestCustom.ctest的顺序逐个检查.cmake扩展名优先——只有CTestCustom.cmake不存在时才回退到CTestCustom.ctest目录非递归只检查给定目录直接路径下的文件dir/CTestCustom.ext不会递归搜索子目录每个目录最多读取一个文件文档中 Read all the CTestCustom.ctest or CTestCustom.cmake files 指的是对每个传入目录的完整处理依次尝试两种扩展名而非把一个目录下所有同名文件全部读入文件不存在时静默跳过若两种扩展名均不存在fname为空字符串命令不做任何操作、不报错便于对目录统一执行而无需逐一判断。读取与错误处理机制找到文件后实现通过cmMakefile::ReadListFile以 CMake 脚本方式解析执行该文件并做了细致的错误隔离bool erroroc cmSystemTools::GetErrorOccurredFlag(); cmSystemTools::ResetErrorOccurredFlag(); if (!mf-ReadListFile(fname) || cmSystemTools::GetErrorOccurredFlag()) { cmCTestLog(this, ERROR_MESSAGE, Problem reading custom configuration: , fname, \n); } if (erroroc) { cmSystemTools::SetErrorOccurred(); }要点解读自定义配置文件本质上是一段被include进当前 makefile 上下文的 CMake 脚本因此文件内可以执行任意 CMake 命令、设置变量、调用message()等读取失败文件解析错误或执行出错时会输出错误消息Problem reading custom configuration: file但会先保存并恢复原有的错误标志位避免污染外层脚本的错误状态调试模式下--debug会打印 * Check for file: ... 与 * Read custom CTest configuration file: ... 等日志可用于排查文件为何未被加载。默认行为二进制目录与 ctest_start 的隐式调用命令文档明确指出不带脚本调用ctest(1)时默认从二进制目录读取自定义文件。这一点在源码中有两处印证CTest 启动阶段会自动处理二进制目录下的自定义配置ctest_start命令内部同样会触发读取——见 Source/CTest/cmCTestStartCommand.cxxthis-CTest-ReadCustomConfigurationFileTree(bld_dir, mf);也就是说在ctest_start()被调用时CTest 会自动对构建目录执行与ctest_read_custom_files(binary_dir)等价的读取动作。这解释了为什么大多数项目只需把CTestCustom.cmake放进构建目录即可生效无需手动调用本命令。该命令在 CTest 脚本模式下的注册位置为 Source/CTest/cmCTestScriptHandler.cxx属于 CTest 脚本处理器内置命令集合state-AddBuiltinCommand(ctest_read_custom_files, cmCTestReadCustomFilesCommand(this-CTest));实战编写并加载 CTestCustom 配置文件何时需要手动调用本命令项目使用ctest -S script.cmake脚本模式且自定义配置文件位于非二进制目录的路径需要在同一个脚本中从多个目录加载自定义配置自定义配置文件名或位置不符合默认约定需要显式指定来源目录。最小示例假设项目的测试自定义配置位于源码树下的cmake/CTestCustom.cmake# 文件cmake/CTestCustom.cmake message(Loading project custom CTest configuration) set(CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS 100) set(CTEST_CUSTOM_WARNING_EXCEPTION C4996;LNK4221 # 示例忽略的警告模式 )在 CTest 脚本ctest -S my_driver.cmake中加载它cmake_minimum_required(VERSION 3.20) # 显式从源码目录加载自定义配置 ctest_read_custom_files( ${CMAKE_CURRENT_LIST_DIR}/cmake ${CMAKE_CURRENT_LIST_DIR}/tests ) ctest_start(...) ctest_configure(...) ctest_build(...) ctest_test(...)执行后脚本会把第一个存在的CTestCustom.cmake/CTestCustom.ctest读入当前上下文后续ctest_*步骤即可使用其中定义的变量。CTestCustom 文件中的变量约定自定义配置文件的核心用途是覆写 CTest 的自定义变量。CTest 的CTEST_CUSTOM_XXX系列变量由ctest(1)初始化但可以在 CTestCustom 文件中编辑这一点在 Help/variable/include/CTEST_CUSTOM_XXX.rst 中有明确说明。从源码看CTest 在配置阶段会通过 Source/cmCTest.cxx 的PopulateCustomVector与PopulateCustomInteger从当前 makefile 定义中取出这些变量分别填充为字符串列表与整数用于控制 CTest 的各环节行为例如警告/错误扫描、测试命令、覆盖率工具参数等void cmCTest::PopulateCustomVector(cmMakefile* mf, std::string const def, std::vectorstd::string vec) { cmValue dval mf-GetDefinition(def); if (!dval) { return; } ... cmList::assign(vec, *dval); }因此在 CTestCustom 文件中set(CTEST_CUSTOM_XXX ...)的写法会直接影响后续测试、构建与覆盖率处理逻辑。同时使用 .ctest 与 .cmake 的注意点由于同一目录下.cmake扩展名优先若同时存在CTestCustom.cmake与CTestCustom.ctest只会读取前者。若两种文件需要同时生效应分别放到不同目录并分两次传入目录参数不同目录之间互不影响。递归与边界场景仓库测试的验证仓库在 Tests/RunCMake/MaxRecursionDepth/ 下提供了针对该命令的回归测试用于验证其递归深度与错误处理行为测试脚本 Tests/RunCMake/MaxRecursionDepth/test.cmake.in 中当TEST_NAME为ctest_read_custom_files时先设置变量x为 2再调用ctest_read_custom_files读取测试源目录下的配置被读取的 Tests/RunCMake/MaxRecursionDepth/CTestCustom.cmake 内容为message(${x}) math(EXPR x ${x} 1) ctest_read_custom_files(${CMAKE_CURRENT_LIST_DIR})即该自定义文件会在每次读取时打印当前x值、递增x并再次调用ctest_read_custom_files指向自身目录形成自我递归加载测试框架 Tests/RunCMake/MaxRecursionDepth/RunCMakeTest.cmake 通过run_ctest_recursive(ctest_read_custom_files)覆盖了默认、变量设置CMAKE_MAXIMUM_RECURSION_DEPTH及环境变量版本等多种场景并配合ctest_read_custom_files-*-stderr.txt基准输出验证错误信息与递归上限行为。该测试同时揭示了两个重要事实ctest_read_custom_files读取的文件内可以再次调用该命令本身以及嵌套include等其他递归加载手段因此受CMAKE_MAXIMUM_RECURSION_DEPTH递归深度限制约束参见 Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst该命令的读取行为与普通 CMake 脚本执行一致可在自定义文件中定义变量、执行命令乃至继续加载其他配置文件。常见问题与排查要点命令报 called with incorrect number of arguments检查是否漏掉了目录参数ctest_read_custom_files至少需要一个目录文件未生效确认文件名严格为CTestCustom.cmake或CTestCustom.ctest大小写敏感且位于传入目录的直接路径下可使用ctest --debug -S script.cmake观察 * Check for file: ... 日志确认查找过程同目录双扩展名记住.cmake优先必要时拆分目录或用两次调用分别指向不同目录读取报 Problem reading custom configuration说明文件被找到但解析/执行失败按普通 CMake 脚本语法错误排查文件内容。小结ctest_read_custom_files是 CTest 自定义配置体系中的显式加载入口它以目录为参数、按.cmake优先于.ctest的顺序查找CTestCustom文件并在 CTest 脚本上下文中执行之。理解其默认行为无脚本时读取二进制目录、ctest_start隐式触发、文件查找规则与错误处理细节能帮助你在复杂测试驱动脚本中可靠地组织、加载和调试自定义 CTest 配置。赞分享构建工具开发工具CLI【免费下载链接】CMakeMirror of CMake upstream repository项目地址https://gitcode.com/gh_mirrors/cm/CMake点击查看免费下载相关推荐CMake CTest ctest_run_script 命令详解在 CTest 脚本中嵌套执行其他脚本CMake CTest ctest_run_script 命令详解在 CTest 脚本中嵌套执行其他脚本 ctest_run_script 是 CTest 脚构建工具开发工具CLIF´ 组件命令字典Component Dictionary深度解读从 XML 命令定义到自动生成的命令表F´ 组件命令字典Component Dictionary深度解读从 XML 命令定义到自动生成的命令表 导读 本文以 F´Flight Softwar嵌入式系统编程CMake CTest 的 ctest_update 命令从源码树更新到 Update.xml 提交流程全解析CMake CTest 的 ctest_update 命令从源码树更新到 Update.xml 提交流程全解析 导读 ctest_update 是 CTest构建工具开发工具CLI上一篇Android图形开发入门Grafika项目实战指南下一篇Windows系统字体显示效果全面优化指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考