★ FEATURED ARTICLE 简介面向 Windows x86-64 平台 C 开发者的 CMake 3.30.3 参考文档包适合需要离线查阅构建系统用法、核对命令参数与理解项目配置流程的初中级开发者。内容围绕 CMake 命令行工具、构建系统说明、变量与属性、生成器表达式、预设配置、文件 API 以及 CTest 等主题展开可帮助读者在无法联网时快速定位概念、排查 CMakeLists.txt 配置问题并加深对跨平台构建流程的理解。压缩包共 2000 个文件以 1147 个 txt 文本和 853 个 html 页面为主前者便于检索与摘录后者适合在浏览器中按章节浏览包体约 43.34MB目录组织便于按主题查找。已有 511 人学习适合作为 C 项目构建与 CMake 使用的案头参考资料也可配合实际工程对照查阅命令、变量和测试工具说明。1. cmake-3.30.3-windows-x86-64 不是下一步下一步就完事版本、位数、生成器先对齐cmake-3.30.3-windows-x86-64 这个包名看起来只是版本号加平台后缀真正装起来才发现CMake 在 c windows 工程里从来不是“下一步下一步”就完事。上周某开发者拿着一个跨平台 Demo 来找我README 只写 cmake -B build他本机却是一个 32 位旧版 CMake配置到一半报生成器不支持编译器也找不到。CMake 本身不编译代码它只负责把 CMakeLists.txt 翻译成 MSVC、Ninja 或 MinGW 能吃的构建文件版本、位数、生成器任何一项对不上后面全是玄学报错。这个 3.30.3 的 x86-64 包适合正在 Windows 上做 C 项目、需要固定构建环境的人如果你只是偶尔跑一个脚本系统自带或旧版也许够用但只要开始碰多配置、预设文件和 CI安装包选错一次后面就要花半天擦屁股。2. 装前环境盘点c windows 工具链与 cmake-3.30.3 的依赖关系装 CMake 之前先别急着双击安装包。CMake 在 Windows 上是一个“中间层”它往下要找到编译器往上要接 IDE 或命令行生成器旁边还可能蹲着一个旧版 CMake 抢 PATH。把系统位数、编译器、生成器、旧版本四件事查清楚后面能少走很多回头路。我一般会在一台新机器上先花十分钟做这个盘点比装完再翻日志快得多。2.1 系统位数、磁盘与权限x86-64 安装包的前置条件cmake-3.30.3-windows-x86-64 是 64 位包要求系统本身是 64 位。现在大多数开发机都是 64 位 Windows 10 或 Windows 11但有一个细节容易忽略你当前打开的 PowerShell 可能本身是 32 位进程。系统是 64 位不代表终端进程是 64 位装完 x86-64 包后在 32 位终端里调用路径和注册表视图会跑到另一层后面查 PATH 会越查越乱。# 确认系统架构和当前终端进程位数 [Environment]::Is64BitOperatingSystem [Environment]::Is64BitProcess (Get-CimInstance Win32_OperatingSystem).Caption (Get-CimInstance Win32_OperatingSystem).VersionIs64BitOperatingSystem返回 True 说明系统是 64 位Is64BitProcess返回 False 说明当前 PowerShell 是 32 位需要换成 64 位终端再继续。Caption和Version用来看系统版本太老的 Windows 10 早期版本在长路径和符号链接上会有额外限制C 工程依赖一多就容易撞上。磁盘空间不用太紧张CMake 本体不大但构建目录、编译器缓存和调试符号会迅速膨胀。我一般给工具盘留至少 10 GB工程盘另算。检查磁盘# 查看各盘剩余空间单位 GB Get-PSDrive -PSProvider FileSystem | Select-Object Name, {nFreeGB;e{[math]::Round($_.Free/1GB,1)}}安装权限分两种装到所有用户需要管理员权限装到当前用户不需要。团队机器建议所有用户加系统 PATH个人机器可以当前用户加用户 PATH。两种方式不要同时装两遍否则where cmake会出现两条路径版本一旧一新终端里先命中哪条全看 PATH 顺序。提示安装路径尽量不用中文、空格和特殊符号后面接 Ninja、Makefile 或某些老项目时路径问题会以“找不到文件”的形式出现排查成本很高。2.2 编译器与生成器MSVC、MinGW、Ninja 该选哪个CMake 不提供编译器它只负责生成构建文件。c windows 场景下常见的组合有四类选错生成器比选错 CMake 版本更常见。生成器依赖的编译器适合场景注意点Visual Studio 17 2022MSVC团队 Windows 原生开发、需要 IDE 调试生成器名带年份要和本机安装实例匹配NinjaMSVC 或 MinGW命令行构建、CI、构建速度快必须先有编译器环境变量MinGW MakefilesMinGW g轻量开源工具链、跨平台小项目位数和异常模型要和依赖库一致NMake MakefilesMSVC nmake老项目、历史工程环境配置繁琐新手容易卡住先看本机有什么编译器# 分别检查 MSVC、MinGW、Ninja 是否在 PATH 里 where.exe cl where.exe g where.exe ninjacl不在 PATH 里是正常现象MSVC 编译器通常要通过开发者命令提示符或vcvars64.bat初始化后才可见。g能找到时用g --version看位数和版本32 位 g 配 64 位 CMake 不会让 CMake 本体报错但生成出来的目标位数会和依赖库对不上。ninja --version能输出版本号即可Ninja 本身很小装在哪里都行关键是 PATH 稳定。再看 CMake 3.30.3 支持哪些生成器# 列出当前 CMake 支持的生成器确认目标生成器名称 cmake --help | Select-String -Pattern Visual Studio|Ninja|MinGW|NMake这条命令在装完 CMake 之后才有意义但可以先记下来。生成器名称是大小写和空格都敏感的Visual Studio 17 2022少一个年份或写成VS2022都会报找不到生成器。MinGW 用户还要注意-G MinGW Makefiles和-G Unix Makefiles不是一回事后者在 Windows 上通常需要 MSYS 环境。2.3 旧版 CMake 清理与共存策略很多机器上已经有一个 CMake可能来自某个 IDE 自带、某个 SDK 附带或者以前装过 3.20 之类的版本。直接覆盖安装不是不行但旧项目的CMakeCache.txt里记着旧编译器路径换版本后缓存不认账会出现一些看起来毫无道理的配置失败。先查清楚# 查看当前终端实际命中的 cmake 路径和版本 where.exe cmake cmake --versionwhere.exe会按 PATH 顺序列出所有同名可执行文件第一条就是当前生效的。cmake --version输出里第一行是版本号第二行是版权信息第三行是系统架构。如果版本不是 3.30.3先别急着删旧版继续看 PATH# 把 PATH 拆开只看包含 cmake 的条目 $env:Path -split ; | Select-String -Pattern cmake|CMakeWindows 的 PATH 合并规则是系统 PATH 和用户 PATH 拼在一起具体顺序在不同终端里可能不一样。常见做法是保留旧版把 3.30.3 装到独立目录然后用一个包装脚本固定调用不要和系统里已有的cmake.exe抢名字。echo off rem 固定调用 cmake-3.30.3避免 PATH 里旧版抢先 set CMAKE_HOMED:\Tools\cmake-3.30.3-windows-x86_64 %CMAKE_HOME%\bin\cmake.exe %*这个脚本可以命名为cmake330.bat不要命名为cmake.bat否则在 PATH 里可能递归调用自己。%*表示把收到的所有参数原样转发给真正的 cmake.exe。项目级隔离时我一般直接写绝对路径或者在 CI 脚本里把CMAKE_HOME设成环境变量不依赖全局 PATH。3. 下载与安装 cmake-3.30.3安装器、便携包和命令行三种路径拿到 cmake-3.30.3-windows-x86-64 之后先决定用 MSI 安装器还是 ZIP 便携包。MSI 会写注册表、带卸载入口适合长期用的开发机ZIP 不写系统痕迹适合多版本共存、临时环境或没有管理员权限的机器。两条路都能跑通关键是别装到一半又混用另一种方式最后 PATH 里出现两个版本。3.1 校验安装包文件名、哈希与架构别装错文件名里通常带windows-x86_64这是 64 位 Windows 包。如果拿到的是windows-i386或没有架构后缀先确认是不是拿错了。校验分两步哈希和数字签名。哈希用来确认文件在传输过程中没有损坏数字签名用来确认文件来源可信。# 计算 SHA256和可信渠道公布的值对比 Get-FileHash .\cmake-3.30.3-windows-x86_64.msi -Algorithm SHA256 # 检查安装包的数字签名状态 Get-AuthenticodeSignature .\cmake-3.30.3-windows-x86_64.msi | Format-List Status, SignerCertificateGet-FileHash的输出里Hash字段是一长串十六进制必须和发布方给出的值完全一致差一个字符都说明文件不对。Get-AuthenticodeSignature的Status应该是Valid如果显示NotSigned或HashMismatch不要继续安装。ZIP 包没有 MSI 的签名入口可以解压后对bin\cmake.exe单独做一次签名检查# ZIP 包解压后检查核心可执行文件的签名 Get-AuthenticodeSignature .\bin\cmake.exe | Format-List Status, SignerCertificate签名检查不是每次都必须做但从外部拿到的安装包我建议至少做一次。哈希对不上时不要抱着“说不定能用”的心态继续CMake 安装包损坏后可能装到一半失败残留的注册表和 PATH 条目比没装还难清理。3.2 图形安装器一路下一步时真正要改的选项MSI 安装器打开后前面几页是许可协议和安装位置真正需要留意的是安装范围和 PATH 选项。安装范围选“为所有用户安装”会写到系统目录需要管理员权限选“仅为我安装”会写到用户目录不需要提权。PATH 选项一般有三个不添加、添加到用户 PATH、添加到系统 PATH。团队机器选系统 PATH个人机器选用户 PATH别两个都选。安装目录我一般改成D:\Tools\cmake\3.30.3不放在默认的Program Files下面。不是默认路径不能用而是后面排错时路径短一点、没有空格复制粘贴到脚本里少一层引号嵌套。图形界面一路点完后新开一个终端验证# 新开终端后确认版本和路径 where.exe cmake cmake --version如果where.exe第一条不是D:\Tools\cmake\3.30.3\bin\cmake.exe说明 PATH 里还有旧条目排在前面回到第 4 章处理 PATH 顺序。需要静默安装时可以用 msiexec 加参数# 静默安装到所有用户并写入系统 PATH msiexec /i .\cmake-3.30.3-windows-x86_64.msi /qn /norestart /l*v .\cmake-install.log ALLUSERS1 ADD_CMAKE_TO_PATHSystem/qn表示无界面安装/norestart禁止安装器自动重启/l*v把详细日志写到当前目录出问题时先看这个日志。ALLUSERS1对应所有用户安装ADD_CMAKE_TO_PATHSystem表示写系统 PATH。这个命令需要管理员权限的终端普通 PowerShell 会直接失败。卸载时用/x# 卸载 MSI 安装的 CMake msiexec /x .\cmake-3.30.3-windows-x86_64.msi /qn卸载不会自动清理你手动加过的 PATH 条目卸完还要检查一遍 PATH把残留路径删掉。3.3 便携 zip 包的解压位置与目录结构ZIP 包适合不想写注册表、或者机器上已经有一个 CMake 但不想动它的情况。解压位置建议固定比如D:\Tools\cmake-3.30.3-windows-x86_64。不要解压到下载目录下载目录里的文件迟早会被清理PATH 指向一个不存在的路径比没加 PATH 更隐蔽。# 解压便携包到固定工具目录 Expand-Archive -Path .\cmake-3.30.3-windows-x86_64.zip -DestinationPath D:\Tools\cmake-3.30.3 -Force # 查看解压后的关键目录 Get-ChildItem D:\Tools\cmake-3.30.3 -Depth 2 | Select-Object FullName解压后重点看bin目录里面应该有cmake.exe、ctest.exe、cpack.exe。share\cmake-3.30是模块目录CMake 找FindXXX.cmake时会用到。ZIP 包有时会多一层同名目录解压后如果看到D:\Tools\cmake-3.30.3\cmake-3.30.3-windows-x86_64\bin说明多套了一层PATH 要指向真正含cmake.exe的那层。# 不依赖 PATH直接用绝对路径验证便携包 D:\Tools\cmake-3.30.3\bin\cmake.exe --version输出第一行应该是cmake version 3.30.3。如果输出旧版本说明你调用的不是这个路径下的 exe检查路径拼写和是否多套了一层目录。便携包不会自动加 PATH后面第 4 章会讲怎么安全地加。安装方式写注册表自动加 PATH适合场景卸载方式MSI 安装器是可选长期开发机、团队统一环境控制面板或 msiexec /xZIP 便携包否否多版本共存、临时环境、无管理员权限删除目录并清理 PATH3.4 命令行静默安装参数批量部署时图形界面不现实常用的是 msiexec 参数组合。下面这张表是我自己装机器时记下来的参数不用全背用的时候查一遍。参数含义常见取值/i安装指定 MSI安装包路径/x卸载指定 MSI安装包路径/qn无界面模式无/norestart禁止自动重启无/l*v详细日志日志文件路径ALLUSERS1所有用户安装1 或空ADD_CMAKE_TO_PATH写入 PATHSystem或User静默安装完成后不要假设 PATH 立刻在所有已打开的终端里生效。Windows 终端会缓存环境变量新开的窗口才会读到新 PATH。验证时用新窗口# 新开管理员终端后验证静默安装结果 cmake --version where.exe cmake如果cmake --version报“不是内部或外部命令”先看安装日志里有没有Return value 3有的话说明安装过程失败日志里会带具体错误码。没有失败但命令找不到多半是 PATH 没写进去回到第 4 章手动补。4. 配置环境变量与生成器让 cmake 在任意终端都能跑装完 CMake 只是把 exe 放到了磁盘上真正让它“在任意终端都能跑”的是 PATH 和生成器配置。PATH 决定你敲cmake时命中哪个版本生成器决定 CMake 把构建文件翻译成 MSVC 还是 Ninja 的格式。这两件事分开配配错一个都会在配置阶段翻车。4.1 PATH 的三层写法用户变量、系统变量与临时会话PATH 可以改在三个地方作用范围完全不同。层级作用范围修改方式风险用户 PATH当前用户所有新终端环境变量界面或 PowerShell写坏只影响当前用户系统 PATH所有用户所有新终端管理员权限修改写坏影响整机需要备份临时会话 PATH当前终端窗口$env:Path赋值关窗口即失效适合测试我一般先用临时会话验证路径没错再写用户 PATH。临时会话这样加# 只在当前 PowerShell 窗口生效关掉就恢复 $env:Path D:\Tools\cmake-3.30.3\bin;$env:Path cmake --version where.exe cmake$env:Path是当前进程的环境变量赋值后只影响这个窗口。where.exe cmake第一条应该是刚加的路径第二条可能是系统里的旧版。确认无误后写用户 PATH# 安全追加用户 PATH不覆盖原有内容 $cmakeBin D:\Tools\cmake-3.30.3\bin $userPath [Environment]::GetEnvironmentVariable(Path, User) if (($userPath -split ;) -notcontains $cmakeBin) { [Environment]::SetEnvironmentVariable( Path, $cmakeBin;$userPath, User ) }这段脚本先读用户 PATH按分号拆开检查是否已经包含目标路径没有才拼到最前面。拼到最前面是为了让 3.30.3 优先于旧版但系统 PATH 里的条目可能仍然排在用户 PATH 前面具体顺序要看终端。写系统 PATH 需要管理员权限把User换成Machine风险更高改之前先导出备份# 修改系统 PATH 前先备份到文件 [Environment]::GetEnvironmentVariable(Path, Machine) | Set-Content .\system-path-backup.txtPATH 写完后必须新开终端旧窗口不会自动刷新。新窗口里再跑一遍where.exe cmake确认顺序符合预期。4.2 CMakePresets.json 与 -G 参数把生成器固定下来生成器可以在命令行用-G临时指定也可以写进CMakePresets.json固定下来。项目一旦多人协作我倾向于用 presets把生成器、构建目录、缓存变量都写进文件新人拉下来直接cmake --preset不用猜别人用的什么参数。{ version: 6, configurePresets: [ { name: dev, displayName: Dev (Ninja MSVC), generator: Ninja, binaryDir: ${sourceDir}/build/dev, cacheVariables: { CMAKE_BUILD_TYPE: Debug, CMAKE_CXX_STANDARD: 20 } } ], buildPresets: [ { name: dev, configurePreset: dev } ] }version: 6需要 CMake 3.25 及以上3.30.3 能直接读。generator固定为Ninja意味着配置时不再需要-G。binaryDir用${sourceDir}变量指向工程根目录下的build/dev避免源码目录被构建文件污染。cacheVariables里的CMAKE_BUILD_TYPE只对单配置生成器有效Ninja 属于单配置Visual Studio 生成器属于多配置多配置下这个变量会被忽略要用--config Debug指定。# 用预设配置和构建不再手写 -G 和 -B cmake --preset dev cmake --build --preset dev--preset dev会读取CMakePresets.json里同名的 configure preset。--build --preset dev读取 build preset构建目录和配置自动对应。命令行里如果再写-G会和 preset 里的 generator 冲突CMake 可能直接报错或给出警告所以用了 presets 就不要再混-G。不用 presets 时-G的常见写法# Visual Studio 生成器指定 x64 架构 cmake -S . -B build-vs -G Visual Studio 17 2022 -A x64 # Ninja 生成器依赖当前环境的编译器 cmake -S . -B build-ninja -G Ninja-S指定源码目录-B指定构建目录-A x64只对 Visual Studio 生成器有效用来指定目标架构。Ninja 生成器不看-A它直接用当前环境里的cl或g。4.3 和 MSVC 环境变量配合别在普通 cmd 里直接 cmakeVisual Studio 生成器会自动定位本机的 MSVC 实例不需要提前跑vcvars64.bat。Ninja 生成器不一样它直接调用cl普通 cmd 里cl不在 PATH配置阶段就会报找不到编译器。常见做法是在开发者命令提示符里跑或者手动调用初始化脚本echo off rem 初始化 64 位 MSVC 环境变量再走 Ninja call %VSINSTALLDIR%\VC\Auxiliary\Build\vcvars64.bat cmake -S . -B build -G Ninja cmake --build build%VSINSTALLDIR%是安装器设置的环境变量指向 IDE 安装根目录。如果这个变量不存在需要手动改成实际路径。vcvars64.bat会把cl.exe、link.exe、Windows SDK 路径写进当前 cmd 会话后面的cmake和ninja才能找到编译器。在 PowerShell 里直接调用 bat 要小心bat 设置的环境变量不一定能回传到 PowerShell 父进程。我一般用cmd /c把整段命令包起来或者干脆在 cmd 里跑完整流程# 用 cmd 一次性执行初始化、配置和构建 cmd /c %VSINSTALLDIR%\VC\Auxiliary\Build\vcvars64.bat cmake -S . -B build -G Ninja cmake --build build这条命令把三条命令串在同一个 cmd 会话里环境变量在会话内有效。路径里有空格时整段要用单引号包住内部再用双引号包路径。PowerShell 的引号嵌套容易写错写完先在终端里跑一遍cl看能不能输出版本再跑 cmake。4.4 多版本共存cmake 3.30.3 与旧项目的兼容开关有些老项目的CMakeLists.txt里写的是cmake_minimum_required(VERSION 3.5)甚至更低CMake 3.30.3 对过低的策略版本会给出警告甚至错误。遇到这种情况不要急着把整台机器的 CMake 换回旧版先看项目能不能改。能改的话把顶层CMakeLists.txt的最低版本提到 3.10 或 3.16再重新配置。不能改的老项目我一般用项目级隔离不碰全局 PATH# 用绝对路径调用 3.30.3构建目录单独命名 D:\Tools\cmake-3.30.3\bin\cmake.exe -S . -B build-330 # 需要旧版时直接调用旧版绝对路径 D:\Tools\cmake-3.20\bin\cmake.exe -S . -B build-320构建目录分开命名避免两个版本的CMakeCache.txt互相污染。CMakeCache.txt里记录了生成器、编译器路径和 CMake 版本换版本后不删缓存配置阶段可能读到旧值出现“编译器已经换了但 CMake 还以为没换”的怪现象。5. 避坑与排查cmake-3.30.3 安装后最常见的五类翻车CMake 的报错信息有时候像黑匣子真正的原因藏在前面几百行日志里。下面五类问题是我装 cmake-3.30.3-windows-x86-64 时踩过的坑按“现象、原因、解决”记下来遇到时先对照别急着重装系统。5.1 现象cmake 不是内部或外部命令现象新开终端敲cmake --version返回“cmake 不是内部或外部命令也不是可运行的程序或批处理文件”。用绝对路径能跑敲命令名就不行。原因PATH 没写进去或者写进去了但终端没刷新。MSI 安装时 PATH 选项选了“不添加”ZIP 包解压后没有手动加 PATH都会出现这个现象。还有一种情况是 PATH 被写坏比如追加时少了分号或者覆盖了原有 PATH。解决先确认 exe 在不在再确认 PATH 里有没有。# 确认安装路径下 exe 存在 Test-Path D:\Tools\cmake-3.30.3\bin\cmake.exe # 查看当前 PATH 里有没有 cmake 目录 $env:Path -split ; | Select-String -Pattern cmake|CMakeTest-Path返回 True 说明文件在问题在 PATH。返回 False 说明路径写错或安装没完成。PATH 里没有目标路径时按第 4 章的脚本追加然后新开终端。PATH 被写坏时用备份文件恢复系统 PATH或者从用户 PATH 里逐条检查把多余的分号、引号、空格清掉。5.2 现象CMake Error: Could not find CMAKE_C_COMPILER现象cmake -S . -B build跑到一半报No CMAKE_C_COMPILER could be found或者CMAKE_CXX_COMPILER not set。原因CMake 找到了生成器但生成器找不到编译器。Ninja 生成器在普通 cmd 里直接跑cl不在 PATHMinGW 生成器选了 32 位 g但工程依赖 64 位库Visual Studio 生成器指向了一个不完整的安装实例。解决先看当前终端有没有编译器再决定用哪个生成器。# 检查编译器是否可见 where.exe cl where.exe g g --versioncl找不到时用开发者命令提示符或vcvars64.bat初始化或者改用 Visual Studio 生成器让 CMake 自己找。g能找到但版本不对时检查 MinGW 的bin目录是不是在 PATH 前面32 位和 64 位不要混用。配置时显式指定生成器减少猜测# 明确用 Ninja并指定 C 和 C 编译器 cmake -S . -B build -G Ninja -DCMAKE_C_COMPILERcl -DCMAKE_CXX_COMPILERclCMAKE_C_COMPILER和CMAKE_CXX_COMPILER只在第一次配置时生效已经生成过CMakeCache.txt的构建目录要先删掉再配。5.3 现象生成器版本不匹配 / 找不到 Visual Studio 实例现象cmake -G Visual Studio 17 2022报Could not find any instance of Visual Studio或者生成器名称直接不被识别。原因生成器名和本机安装的 IDE 版本不对应。Visual Studio 17 2022对应 2022 版装的是更早或更晚的版本就对不上。另一种原因是 IDE 安装时没勾选 C 工作负载CMake 能找到安装目录但找不到编译器。解决先用cmake --help看当前 CMake 支持的生成器列表列表里的名称一字不差地抄。# 只列出 Visual Studio 相关生成器 cmake --help | Select-String -Pattern Visual Studio列表里没有Visual Studio 17 2022说明 CMake 版本太旧或太新换一个匹配的生成器名。列表里有但配置时报找不到实例检查 IDE 安装器里有没有勾选 C 桌面开发工作负载。实在不想折腾 IDE可以改用 Ninja 加vcvars64.bat绕开实例查找。5.4 现象中文路径与空格路径导致配置失败现象工程放在D:\工作\我的项目或C:\Users\Some Name\Desktop\demo配置阶段报找不到文件、路径截断、或者生成出来的构建文件里路径乱码。原因CMake 本身对中文路径不是完全不能处理但下游的编译器、链接器、Ninja、Makefile 对空格和中文字符的容忍度不一样。路径里带空格时某些老脚本拼命令行少加引号参数会被拆成两段中文路径在代码页不一致的终端里会变成乱码。解决工程目录和构建目录都放到纯英文、无空格的路径下比如D:\work\demo。检查当前路径# 看当前路径里有没有空格或非 ASCII 字符 $pwd.Path $pwd.Path -match [^\x00-\x7F]第二条返回 True 说明路径里有非 ASCII 字符。能挪就挪不能挪时至少把构建目录放到纯英文路径用-B D:\build\demo指定。源码路径实在不能动再考虑短路径或符号链接但那属于补救不如一开始就放对位置。5.5 现象旧缓存 CMakeCache.txt 让新版本行为异常现象换了 CMake 3.30.3 或换了编译器重新配置时 CMake 仍然用旧路径、旧生成器甚至报一些和当前工程无关的错误。原因构建目录里的CMakeCache.txt记录了上一次配置的生成器、编译器、CMake 版本和大量缓存变量。CMake 默认会复用缓存不会自动清掉旧值。旧缓存和新环境冲突时报错信息往往指向缓存里的旧路径看起来像灵异事件。解决换版本、换编译器、换生成器时直接删构建目录或者用--fresh清缓存。CMake 3.24 及以上支持--fresh3.30.3 可以直接用。# 方式一删除整个构建目录最干净 Remove-Item -Recurse -Force .\build # 方式二保留目录只清缓存重新配置 cmake --fresh -S . -B build -G NinjaRemove-Item -Recurse -Force会连构建产物一起删适合不心疼编译时间的场景。--fresh只清缓存保留目录结构配置速度稍快。不管用哪种清完缓存后第一次配置要重新指定生成器和编译器别指望 CMake 记住上一次的选择。6. 验证安装跑通用一个最小 C 工程验收 cmake-3.30.3装完 CMake 最怕“命令能跑但工程配不出来”。我一般用一个最小 C 工程做验收不依赖任何第三方库只验证 CMake 能找到编译器、能生成构建文件、能编出可执行文件。这个工程放在D:\work\cmake-smoke路径纯英文无空格。先建两个文件# CMakeLists.txt最低版本写 3.16兼容大部分现代工程 cmake_minimum_required(VERSION 3.16) project(cmake_smoke LANGUAGES CXX) # 固定 C 标准避免不同编译器默认值不一致 set(CMAKE_CXX_STANDARD 20) set(CMAKE_CXX_STANDARD_REQUIRED ON) add_executable(smoke main.cpp)// main.cpp只打印 CMake 版本和 C 标准验证编译链路 #include iostream int main() { std::cout cmake smoke ok std::endl; #if __cplusplus 202002L std::cout c20 std::endl; #else std::cout c standard: __cplusplus std::endl; #endif return 0; }cmake_minimum_required(VERSION 3.16)是给 CMake 3.30.3 一个明确的策略版本避免落到过低的兼容分支。project(... LANGUAGES CXX)只启用 C不启用 C配置阶段少检查一个编译器。CMAKE_CXX_STANDARD 20和CMAKE_CXX_STANDARD_REQUIRED ON一起用编译器不支持 C20 时直接报错而不是悄悄降级。配置和构建分两步# 进入工程目录用 Ninja 生成器配置 cd D:\work\cmake-smoke cmake -S . -B build -G Ninja # 构建并运行 cmake --build build .\build\smoke.exe-S .表示源码目录是当前目录-B build表示构建目录是build-G Ninja表示用 Ninja 生成器。如果本机没有初始化 MSVC 环境这一步会报找不到编译器回到第 4.3 节用vcvars64.bat初始化。构建成功后运行smoke.exe输出cmake smoke ok和c20说明整条链路通了。再核对几项关键信息核对项命令期望结果CMake 版本cmake --version第一行包含3.30.3CMake 路径where.exe cmake第一条指向 3.30.3本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
