sublime text 里用 cmake-format 前必须确认三件事：一是终端能识别 cmake-format 命令（via which/where），二是 sublime 构建系统能调用该命令（需显式指定路径或 shell_cmd），三是 .cmake-format 配置文件必须置于项目根目录且字段名准确无误。
Sublime Text 里用 cmake-format 前必须确认的三件事
cmake-format 不是开箱即用的格式化工具，它依赖 Python 环境、正确安装的 cmake-format 包、以及 Sublime 能调用到该命令——缺一不可。常见失败现象是 Ctrl+Shift+P 输入 “CMake Format” 后无响应，或执行时报 command not found: cmake-format。
- 先在终端运行
which cmake-format（macOS/Linux）或where cmake-format（Windows），确认命令真实路径；若无输出，说明没装或不在 PATH 中 - 不要用
pip install cmake-format直接装——它默认装在用户 site-packages，但 Sublime 的 Python 环境可能不识别；推荐用虚拟环境或系统级 pip 安装，并确保该环境被 Sublime 构建系统继承 - Sublime 默认不读取 shell 的 PATH（尤其 Windows 下的 CMD/PowerShell），所以即使终端能跑，Sublime 可能找不到；解决方法是：在 Build System 配置中显式指定
"cmd": ["<code>/path/to/cmake-format", "-i", "$file"]，或改用"shell_cmd"模式并包裹bash -c "cmake-format -i '$file'"
cmake-format 配置文件必须放在项目根目录才生效
cmake-format 不像 clang-format 那样支持逐层向上查找 .clang-format；它只认当前文件所在目录或其父级中第一个 .cmake-format 文件。如果你把配置文件放在 src/ 或 cmake/ 子目录下，对 CMakeLists.txt（通常在项目根）无效。
- 标准做法：在项目最外层（即含
CMakeLists.txt的目录）放一个.cmake-format，内容示例：{ "line_width": 120, "tab_size": 2, "max_subargs_per_line": 4, "separate_ctrl_name_with_space": true, "dangle_parens": false } - 注意字段名大小写敏感，
tab_size不是indent_size；错误拼写会导致配置静默失效 - Sublime 插件（如 CMake Format）一般不自动重载配置，改完
.cmake-format后需重启 Sublime 或手动触发重新加载（部分插件支持 Ctrl+Shift+P → “CMake Format: Reload Config”）
CMake Tools 插件和 cmake-format 不能共用同一套缩进逻辑
EditorConfig 和 CMake Tools 插件各自维护缩进规则，而 cmake-format 会按自己配置强制重排——三者冲突时，cmake-format 优先级最高，且不尊重 indent_style 或 indent_size 设置。结果就是：你设了 indent_style = space、indent_size = 4，但 cmake-format 仍按 tab_size = 2 插入空格或制表符。
- 根本原因：cmake-format 是独立 Python 工具，完全不读
.editorconfig；它的缩进由tab_size和space_before_comment等字段控制，与 EditorConfig 无关 - 解决方案不是禁用 EditorConfig，而是统一源头：把
.cmake-format中的tab_size设为和团队.editorconfig一致的值（比如都用 4），避免视觉撕裂 - 如果项目同时用 CMake Tools + cmake-format，务必关掉 CMake Tools 的 “Auto-format on save”（如有），否则它可能在 configure 后自动重排，和 cmake-format 冲突
CI 流水线里 cmake-format 检查必须加 --check 参数
本地格式化用 -i（in-place）没问题，但在 Git hook 或 CI 中直接 cmake-format -i *.txt 会悄悄改代码，违背“检查先行”原则。更严重的是，某些旧版 cmake-format（--check 模式下 exit code 不规范，导致 CI 误判通过。
- 推荐 CI 命令：
cmake-format --check --first-comment-line-regex '^[ \t]*#[^!]' CMakeLists.txt cmake/*.cmake；其中--first-comment-line-regex是为了兼容带 shebang 的脚本（如#!/usr/bin/env cmake） - 务必验证 cmake-format 版本：
cmake-format --version；低于 0.6.14 的版本在--check下即使有差异也返回 0，必须升级 - Sublime 插件通常不暴露
--check功能，所以 CI 检查不能依赖插件行为，必须走独立命令行调用
find_package() 和 target_link_libraries() 的参数换行策略极其敏感，一行写太长会被强制拆，但拆错位置（比如把 PRIVATE 拆到下一行）会导致 CMake 解析失败。这类细节不会报错，却让构建在 CI 上突然失败——得靠人工 review 或加额外的语法校验步骤兜底。
