CMake .cmake 模块与 Preset：可复现构建的拆分技巧

2026-07-20T00:00:00+00:00

.cmake</code> 模块与 Preset 使用技巧</h1>
根目录 CMakeLists.txt</code> 一旦堆满 find_package</code>、警告选项、生成器判定，项目会很快「能编但难讲」。更稳的做法是：</p>

按职责拆 .cmake</code> 模块</strong>（工具链 / 生成器 / 警告 / 日志 / 安装）</li>
用 CMakePresets.json</code> 固定常用组合</strong>（本机 Ninja、CI Release、开 tidy 等）</li>
</ol>
本文是实操向清单，偏 CMake 3.20+ / 4.x。</p>

1. 为什么要拆 .cmake</code></h2>
问题</th> 拆模块后</th></tr></thead>

新人不知道改哪</td> README 写「改 cmake/ToolchainClang.cmake</code>」</td></tr>
AppleClang / Homebrew LLVM 混用</td> 工具链探测集中一处</td></tr>
生成器搞错（modules 需要 Ninja）</td> Generator.cmake</code> 统一 FATAL</td></tr>
选项满天飞</td> preset 命名表达意图</td></tr>
</tbody></table>
建议分层（名字可自定，职责别混）：</p>
cmake/</span></span>
  Generator.cmake          # 强制/探测生成器</span></span>
  ToolchainClang.cmake     # 编译器、sysroot、modules JSON</span></span>
  StdlibConfig.cmake       # import std / stdlib 探测</span></span>
  CompilerWarnings.cmake   # -Wall 与可选 tidy</span></span>
  BuildLog.cmake           # 彩色日志 / tee</span></span>
  ProjectSetup.cmake       # 打印关键变量摘要</span></span>
  Modules.cmake            # 挂 CXX modules 相关</span></span></code></pre>
根 CMakeLists.txt</code> 只做：project()</code>、add_subdirectory</code> / add_executable</code>、按顺序 include()</code>。</p>

2. .cmake</code> 编写技巧</h2>
2.1 用 option()</code> / CACHE</code> 暴露开关，默认保守</h3>
option</span>(CXX_ENABLE_CLANG_TIDY </span>"</span>Enable clang-tidy</span>"</span> OFF</span>)</span></span>
option</span>(CXX_ENABLE_GTEST </span>"</span>Build tests</span>"</span> OFF</span>)</span></span>
set</span>(CXX_PREFERRED_COMPILER </span>"</span>clang++</span>"</span> CACHE</span> STRING</span> "</span>clang++|g++</span>"</span>)</span></span></code></pre>
默认 OFF，避免「拉下来编不过」。</p>
2.2 致命条件用清晰单行字符串</h3>
CMake 的 list</code> 与多参数 set(msg "a" "b")</code> 容易把 FATAL_ERROR</code> 显示成空白。拼错误信息时用 string(APPEND)</code>：</p>
set</span>(_err </span>"</span>"</span>)</span></span>
string</span>(APPEND _err </span>"</span>Ninja is required for C++23 modules.</span>\n</span>"</span>)</span></span>
string</span>(APPEND _err </span>"</span>Hint: export CMAKE_GENERATOR=Ninja or use -G Ninja</span>"</span>)</span></span>
message</span>(FATAL_ERROR </span>"</span>${_err}</span>"</span>)</span></span></code></pre>2.3 生成器：早失败</h3>
if</span>(</span>NOT</span> CMAKE_GENERATOR</span> STREQUAL</span> "</span>Ninja</span>"</span>)</span></span>
  message</span>(FATAL_ERROR </span>"</span>Use Ninja (C++ modules / import std). Got: ${CMAKE_GENERATOR}</span>"</span>)</span></span>
endif</span>()</span></span></code></pre>
配合根目录 .envrc</code>：export CMAKE_GENERATOR=Ninja</code>，减少「裸 cmake ..</code> 掉进 Unix Makefiles」的缓存坑。</p>
2.4 include 顺序要稳定</h3>
典型顺序：</p>
include</span>(cmake/Generator.cmake)</span></span>
include</span>(cmake/ToolchainClang.cmake)</span></span>
include</span>(cmake/StdlibConfig.cmake)</span></span>
# … project() 之后再：</span></span>
include</span>(cmake/CompilerWarnings.cmake)</span></span>
include</span>(cmake/ProjectSetup.cmake)</span></span></code></pre>
工具链相关尽量在 project()</code> 前完成；依赖 PROJECT_*</code> 的摘要放后面。</p>

3. CMakePresets.json</code> 技巧</h2>
3.1 最小结构</h3>
{</span></span>
  "</span>version</span>"</span>:</span> 6</span>,</span></span>
  "</span>configurePresets</span>"</span>:</span> [</span></span>
    {</span></span>
      "</span>name</span>"</span>:</span> "</span>dev</span>"</span>,</span></span>
      "</span>displayName</span>"</span>:</span> "</span>Dev (Ninja RelWithDebInfo)</span>"</span>,</span></span>
      "</span>generator</span>"</span>:</span> "</span>Ninja</span>"</span>,</span></span>
      "</span>binaryDir</span>"</span>:</span> "</span>${sourceDir}/build</span>"</span>,</span></span>
      "</span>cacheVariables</span>"</span>:</span> {</span></span>
        "</span>CMAKE_BUILD_TYPE</span>"</span>:</span> "</span>RelWithDebInfo</span>"</span>,</span></span>
        "</span>CXX_PREFERRED_COMPILER</span>"</span>:</span> "</span>clang++</span>"</span>,</span></span>
        "</span>CXX_ENABLE_CLANG_TIDY</span>"</span>:</span> "</span>OFF</span>"</span></span>
      }</span></span>
    }</span>,</span></span>
    {</span></span>
      "</span>name</span>"</span>:</span> "</span>tidy</span>"</span>,</span></span>
      "</span>inherits</span>"</span>:</span> "</span>dev</span>"</span>,</span></span>
      "</span>displayName</span>"</span>:</span> "</span>Dev + clang-tidy</span>"</span>,</span></span>
      "</span>cacheVariables</span>"</span>:</span> {</span></span>
        "</span>CXX_ENABLE_CLANG_TIDY</span>"</span>:</span> "</span>ON</span>"</span></span>
      }</span></span>
    }</span></span>
  ]</span>,</span></span>
  "</span>buildPresets</span>"</span>:</span> [</span></span>
    {</span> "</span>name</span>"</span>:</span> "</span>dev</span>"</span>,</span> "</span>configurePreset</span>"</span>:</span> "</span>dev</span>"</span> }</span>,</span></span>
    {</span> "</span>name</span>"</span>:</span> "</span>tidy</span>"</span>,</span> "</span>configurePreset</span>"</span>:</span> "</span>tidy</span>"</span> }</span></span>
  ]</span></span>
}</span></span></code></pre>3.2 实用习惯</h3>
技巧</th> 说明</th></tr></thead>

inherits</code></td> 共用 generator</code> / binaryDir</code>，只覆盖差异</td></tr>
binaryDir</code> 固定 build/</code></td> 与文档「进 build 再 cmake」一致</td></tr>
显式写 generator: Ninja</code></td> 不依赖环境变量也正确</td></tr>
分开 dev</code> / ci</code> / tidy</code></td> 意图可读，少口头约定</td></tr>
勿把本机绝对路径写进 preset</td> 用 ${sourceDir}</code>、环境变量</td></tr>
</tbody></table>
3.3 命令</h3>
cmake</span> -</span>-preset</span> dev</span></span>
cmake</span> -</span>-build</span> -</span>-preset</span> dev</span></span>
</span>
cmake</span> -</span>-preset</span> tidy</span></span>
cmake</span> -</span>-build</span> -</span>-preset</span> tidy</span></span></code></pre>
无 preset 时等价习惯：</p>
mkdir</span> -</span>p</span> build</span> &&</span> cd</span> build</span></span>
cmake</span> -</span>G</span> Ninja</span> ..</span></span>
cmake</span> -</span>-build</span> .</span></span></code></pre>

4. 和 clang-tidy 的组合</h2>

日常：dev</code> preset，tidy OFF</li>
合入前 / CI：tidy</code> preset 或 -DCXX_ENABLE_CLANG_TIDY=ON</code></li>
规则文件：仓库根 .clang-tidy</code>（见专栏上一篇）</li>
</ul>
这样「模块拆分」负责机制</strong>，「preset」负责场景</strong>，两边都不膨胀。</p>

5. 排障速查</h2>
现象</th> 处理</th></tr></thead>

cmake ..</code> 后生成器是 Makefiles</td> rm -rf build && mkdir build</code>，再用 Ninja / preset</td></tr>
FATAL 信息空白</td> 检查是否把错误字符串写成了 CMake list</td></tr>
tidy 找不到</td> PATH 含 Homebrew LLVM；或 find_program</code> 失败时明确 WARNING</td></tr>
preset 不生效</td> 确认 CMakePresets.json</code> 在源码根；CMake ≥ 3.19（建议 3.23+ / 4.x）</td></tr>
</tbody></table>

6. 小结</h2>
把「怎么探测环境」放进 .cmake</code>，把「这次我想怎样编」放进 preset。根 CMakeLists.txt</code> 保持薄，专栏工程和脚手架模板就能共用同一套心智模型。</p>

Rocky‘s Blog - CMakePresets

CMake .cmake 模块与 Preset：可复现构建的拆分技巧

6. 小结</h2>
把「怎么探测环境」放进 `.cmake</code>，把「这次我想怎样编」放进 preset。根 CMakeLists.txt</code> 保持薄，专栏工程和脚手架模板就能共用同一套心智模型。</p>`

Rocky‘s Blog - CMakePresets

CMake .cmake 模块与 Preset：可复现构建的拆分技巧

6. 小结</h2> 把「怎么探测环境」放进 .cmake</code>，把「这次我想怎样编」放进 preset。根 CMakeLists.txt</code> 保持薄，专栏工程和脚手架模板就能共用同一套心智模型。</p>

6. 小结</h2>
把「怎么探测环境」放进 `.cmake</code>，把「这次我想怎样编」放进 preset。根 CMakeLists.txt</code> 保持薄，专栏工程和脚手架模板就能共用同一套心智模型。</p>`