CMake 接入 clang-tidy：从开关到可维护门禁

Suchaharcan — Mon, 20 Jul 2026 00:00:00 +0000

CMake 接入 clang-tidy</h1>

clang-tidy</code> 适合当工程的静态门禁</strong>：比编译器警告更靠近「现代 C++ 习惯」和「API 误用」。难点通常不在「能不能跑」，而在 CMake 怎么挂、配置怎么钉死、本地与 CI 怎么一致</strong>。</p>

本文按「能开关 → 能复现 → 能长期维护」三条线整理。</p>


1. 先弄清两种挂法</h2>
1.1 编译时自动跑（CMAKE_CXX_CLANG_TIDY</code>）</h3>
CMake 会把 tidy 绑到每个编译命令上：改一个 .cpp</code>，编译时顺带分析。</p>
option</span>(CXX_ENABLE_CLANG_TIDY </span>"</span>Attach clang-tidy to CXX compile</span>"</span> OFF</span>)</span></span>
</span>
if</span>(CXX_ENABLE_CLANG_TIDY)</span></span>
  find_program</span>(CLANG_TIDY_EXE </span>NAMES</span> clang-tidy REQUIRED)</span></span>
  set</span>(CMAKE_CXX_CLANG_TIDY</span></span>
    "</span>${CLANG_TIDY_EXE};-warnings-as-errors=*</span>"</span></span>
    CACHE</span> STRING</span> "</span>"</span> FORCE)</span></span>
endif</span>()</span></span></code></pre>
适合：小目标 / 模块化工程 / 想强制「脏代码编不过」</strong>。</p>
代价：全量编译变慢；增量时只扫改过的 TU。</p>
1.2 独立目标 / 脚本扫（不绑编译）</h3>
用 compile_commands.json</code> + 自己的 clang-tidy</code> 调用：</p>
cmake</span> -</span>S</span> .</span> -</span>B</span> build</span> -</span>DCMAKE_EXPORT_COMPILE_COMMANDS=ON</span></span>
clang-tidy</span> -</span>p</span> build</span> src/</span>*</span>*</span>/</span>*</span>.cpp</span></span></code></pre>
适合：大仓库、只想在 PR 跑、或 tidy 与构建解耦</strong>。</p>

2. 配置文件：把规则钉在仓库里</h2>
优先放仓库根或 cmake/</code> 旁的 .clang-tidy</code>，避免每人本机「默认检查集」不一致。</p>
最小可用示例：</p>
C</span>hecks</span>:</span> ></span></span>
  -*,</span></span>
  bugprone-*,</span></span>
  modernize-use-nullptr,</span></span>
  modernize-use-override,</span></span>
  readability-identifier-naming,</span></span>
  performance-unnecessary-copy-initialization</span></span>
W</span>arningsAsErrors</span>:</span> '</span>'</span></span>
H</span>eaderFilterRegex</span>:</span> '</span>.*</span>'</span></span>
F</span>ormatStyle</span>:</span> n</span>one</span></span></code></pre>
经验：</p>
做法</th> 建议</th></tr></thead>

一上来开 *</code></td> 噪音爆炸，团队会关掉 tidy</td></tr>
从 bugprone-*</code> + 少量 modernize 起步</td> 易落地</td></tr>
WarningsAsErrors: '*'</code></td> 适合 CI 门禁；本地可先关</td></tr>
第三方头文件</td> 用 HeaderFilterRegex</code> 限定自己的源码树</td></tr>
</tbody></table>

3. 与 CMake 分层基建的常见接法</h2>
现代工程常把开关放在 CompilerWarnings.cmake</code> / ProjectSetup.cmake</code> 一类文件里，例如：</p>
# cmake/CompilerWarnings.cmake（示意）</span></span>
function</span>(cxx_enable_clang_tidy </span>target</span>)</span></span>
  if</span>(</span>NOT</span> CXX_ENABLE_CLANG_TIDY)</span></span>
    return</span>()</span></span>
  endif</span>()</span></span>
  find_program</span>(CLANG_TIDY_EXE </span>NAMES</span> clang-tidy)</span></span>
  if</span>(</span>NOT</span> CLANG_TIDY_EXE)</span></span>
    message</span>(WARNING </span>"</span>clang-tidy not found; skip</span>"</span>)</span></span>
    return</span>()</span></span>
  endif</span>()</span></span>
  set_target_properties</span>(</span>${target}</span> PROPERTIES</span></span>
    CXX_CLANG_TIDY </span>"</span>${CLANG_TIDY_EXE};--config-file=${CMAKE_SOURCE_DIR}/.clang-tidy</span>"</span>)</span></span>
endfunction</span>()</span></span></code></pre>
对 C++23 modules / import std</code></strong> 工程：确认 tidy 用的 clang 版本与编译器同源（Homebrew LLVM 场景尤其常见），否则会出现「编译过、tidy 解析失败」。</p>

4. 本地工作流（推荐）</h2>
export</span> PATH</span>=</span>"</span>/opt/homebrew/opt/llvm/bin:</span>$</span>PATH</span>"</span></span>
</span>
#</span> 默认关闭 tidy，日常编译快</span></span>
cmake</span> -</span>S</span> .</span> -</span>B</span> build</span> -</span>G</span> Ninja</span></span>
cmake</span> -</span>-build</span> build</span></span>
</span>
#</span> 需要门禁时显式打开</span></span>
cmake</span> -</span>S</span> .</span> -</span>B</span> build</span> -</span>G</span> Ninja</span> -</span>DCXX_ENABLE_CLANG_TIDY=ON</span></span>
cmake</span> -</span>-build</span> build</span></span></code></pre>
把「默认 OFF、CI ON」写进 README / preset，比强迫人人开 tidy 更可持续。</p>

5. CI 门禁清单</h2>


CMAKE_EXPORT_COMPILE_COMMANDS=ON</code>（若用独立扫）</li>

固定 clang-tidy</code> 版本（或固定 LLVM formula 大版本）</li>

.clang-tidy</code> 进仓库</li>

PR 必跑；main 上偶发全量</li>

第三方目录进 .clang-tidy</code> 忽略或 HeaderFilterRegex</code> 排除</li>
</ul>

6. 小结</h2>
目标</th> 做法</th></tr></thead>

开发时提醒</td> 本机可选 CXX_ENABLE_CLANG_TIDY=ON</code></td></tr>
合入质量</td> CI 打开 + warnings-as-errors</code></td></tr>
长期可维护</td> 仓库内 .clang-tidy</code> + 窄检查集逐步加宽</td></tr>
</tbody></table>
下一篇会写 .cmake</code> 模块拆分与 CMakePresets.json</code> 的使用技巧</strong>，和 tidy 开关如何一起放进 preset。</p>

Rocky‘s Blog - clang-tidy

CMake 接入 clang-tidy：从开关到可维护门禁

1. 先弄清两种挂法</h2>