CMake 3.10 Windows安装配置与VS2017旧工程实战指南

简介这是一份适用于Windows 64位系统的CMake 3.10.0安装包主要面向需要在Windows环境下管理跨平台C/C项目构建的开发者与维护者。CMake不直接编译代码而是依据项目中的CMakeLists.txt指令生成Visual Studio解决方案、Makefile、Ninja等构建文件从而统一配置项目目标、源文件、头文件路径与库依赖。借助add_executable、add_library、find_package等常用命令可显著降低大型项目在多种编译器间的迁移成本并为后续的自动化构建和持续集成提供基础。压缩包约18.61MB解压安装后即可在命令行或cmake-gui中完成工程的配置与生成无需额外依赖大型IDE环境。该版本虽非最新但针对Windows 64位做了专门适配对需要稳定构建流程的存量项目仍很实用同时支持与CTest、CPack协同覆盖自动化测试与软件打包环节。目前已有1676人学习下载适合从入门到进阶的Windows端构建工具使用者。1. 为什么还在装 CMake 3.10.0老版本的真实战场现在不少课件、课程设计和老工程还压着 CMake 3.10 这个版本不放并不是大家不想升级而是项目里的 Qt 5.9.4 或 VS2017 的环境配上新版本 CMake 之后生成器行为、find_package 的搜索路径、编译器识别策略全变了反而容易在配置阶段直接翻车。cmake-3.10.0-win64-x64.rar 这个安装包的价值就在于此它是 2018 年初的稳定版支持 Visual Studio 15 2017 生成器解压就能用适合还在维护旧工程的从业者也适合离线开发机上不想折腾环境的人。它能解决的是“在一台装了 VS2017 和 Qt 5.9.4 的老机器上把 CMake 工程稳定配置出来”这件事而不是给你讲最新的 CMake 语法。2. 安装与环境变量把 cmake 命令变成全局可用2.1 先看压缩包里有什么解开之后不要乱动目录结构拿到 cmake-3.10.0-win64-x64.rar先把整个压缩包解压到一个不带空格和中文的路径下比如D:\dev\cmake-3.10.0-win64-x64。注意不要把里面的某个子目录单独拎出来用这个版本对目录完整性比较敏感。压缩包解开后核心部分是这样的bin\cmake.exe命令行主程序bin\cmake-gui.exe图形界面配置工具bin\cpack.exe打包工具生成安装包时用bin\ctest.exe测试运行工具share\cmake-3.10\Modules\find_package、编译器检测等核心模块不能丢很多人在这一步习惯只拷贝bin目录到别的地方后果是运行cmake时直接报Could not find CMAKE_ROOT就是因为share目录没跟上。CMake 的可执行文件会通过相对路径去找自己的模块目录所以千万不要拆着拷贝。2.2 配置 PATH别把路径写死打开 PowerShell用下面的方式临时配置一次验证没问题后再写到系统环境变量里$env:CMAKE_HOME D:\dev\cmake-3.10.0-win64-x64 $env:Path $env:CMAKE_HOME\bin;$env:Path cmake --version这里我习惯先定义一个CMAKE_HOME变量再把它的bin子目录追加到Path而不是把完整的D:\dev\cmake-3.10.0-win64-x64\bin直接写进系统变量。原因是后面如果要写自己的 CMake 模块脚本可以在脚本里用$ENV{CMAKE_HOME}引用这个根目录换版本时只改一个变量就行。如果要用系统级配置右键“此电脑 → 属性 → 高级系统设置 → 环境变量”新建系统变量CMAKE_HOME再在Path里追加%CMAKE_HOME%\bin。注意这里用的是百分号引用不是写死路径。配置好后新开一个终端执行cmake --version where cmakewhere cmake能看到当前实际生效的 cmake 路径如果系统里装过别的版本这一步能立刻发现它指向了哪里。2.3 验证最小可用性不管装什么版本都要先跑一个空配置我一般拿到任何 CMake 环境后都会先在临时目录里跑一次最小配置测试而不是直接去配置大工程mkdir D:\tmp\cmake_test cd D:\tmp\cmake_test cmake -G Visual Studio 15 2017 Win64 .这个命令会提示No CMAKE_CXX_COMPILER could be found或者直接完成配置并生成.sln。如果它报找不到编译器问题通常出在 VS2017 的 C 工具链没装全而不是 CMake 本身有问题。这一步跑通后至少能确认你的 CMake 安装目录是完好的。3. 跑通第一个 CMake 项目命令行构建的底层流程3.1 最小的 CMakeLists.txt 该怎么写一个能运行的最小工程只需要三个文件main.cpp、CMakeLists.txt、一个空的构建目录。新建一个文件夹D:\demo\hello在里面写main.cpp#include iostream int main() { std::cout hello from cmake 3.10 std::endl; return 0; }再写CMakeLists.txtcmake_minimum_required(VERSION 3.10) project(HelloDemo) add_executable(hello_demo main.cpp)这段文件里有三行每行都有明确作用第一行声明最低版本要求CMake 3.10 会按 3.10 的行为规则去解释后面的命令第二行定义工程名同时触发编译器检测第三行把main.cpp编译成可执行文件hello_demo。对于老版本project()这一行尤其敏感如果后面配置阶段报策略相关的警告多半是它的版本声明没写完整。3.2 configure、generate、build 是三个动作不是一个命令很多人以为 CMake 就是“执行一下就能构建”其实它拆成了三个阶段。在D:\demo\hello下执行mkdir build cd build cmake -G Visual Studio 15 2017 Win64 ..这一步同时完成了 configure 和 generateCMake 读取CMakeLists.txt检测编译器生成HelloDemo.sln和一堆.vcxproj文件。紧接着执行cmake --build . --config Debug这才是真正的编译它调用的是 MSVC 的cl.exe而不是 CMake 自己。这里的结构很多人会搞混cmake -G做的是配置和生成cmake --build做的是构建两者之间没有隐式依赖之外的联系。以 VS 生成器为例CMAKE_BUILD_TYPE这个变量是不生效的因为 Visual Studio 是多配置生成器Debug 和 Release 可以同时存在于同一个工程文件里选哪个由--config决定。只有当你用 MinGW Makefiles 或 Unix Makefiles 这类单配置生成器时CMAKE_BUILD_TYPE才有意义。3.3 命令行参数的门道这版有哪些选项能用CMake 3.10 的命令行参数和现在最新的版本相比有一个重要区别它不支持-S和-B这两个简写参数。这两个参数是 CMake 3.13 才加入的在老版本里直接执行cmake -S . -B build会报Unknown argument。旧版的标准姿势是cmake 源码目录并在构建目录里执行上面我写的cmake -G Visual Studio 15 2017 Win64 ..就是这个时代的写法。常用参数基本固定在下面这些参数作用例子-G generator指定生成器-G Visual Studio 15 2017 Win64-D varvalue定义缓存变量-DCMAKE_INSTALL_PREFIXD:/usr--build dir构建已配置的工程cmake --build . --config Release--target name只构建指定目标cmake --build . --target hello_demo每个 CMake 版本能检测到哪些生成器和编译器可以在命令行输入cmake --help查看列表。3.10.0 默认能识别 VS2017 的生成器名是Visual Studio 15 2017 Win64注意这里一定要写Win64否则生成 32 位工程在 64 位库混用时会链接报错。4. 接入第三方库把 SQLite 源码直接编进工程4.1 源码在本地最直接的做法是 add_subdirectoryCMake 3.10 没有 FetchContent它是 3.11 才加入的所以老项目里最常见的集成方式是add_subdirectory。把第三方库的源码目录拖进自己的工程目录然后在CMakeLists.txt里直接引用目标。这里用一个真实场景给上面的hello_demo加上 SQLite3。工程目录结构拉平放在一起D:\demo\hello\ CMakeLists.txt main.cpp sqlite3\ sqlite3.c sqlite3.h sqlite3ext.h CMakeLists.txtsqlite3\CMakeLists.txt写的是cmake_minimum_required(VERSION 3.10) project(sqlite3 C) add_library(sqlite3 STATIC sqlite3.c) target_include_directories(sqlite3 PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})外面的CMakeLists.txt改成cmake_minimum_required(VERSION 3.10) project(HelloDemo) add_subdirectory(sqlite3) add_executable(hello_demo main.cpp) target_link_libraries(hello_demo PRIVATE sqlite3) main.cpp 里可以直接 include sqlite3.h这里的关键逻辑是add_subdirectory会把子目录里的sqlite3目标带过来然后主工程通过target_link_libraries引用它。target_include_directories后面的PUBLIC表示使用方也就是hello_demo也能拿到 sqlite3 的头文件路径不需要在主工程里再手动写include_directories。这种做法的好处是构建时可编译依赖关系完全交给 CMake 管理sqlite3.c和main.cpp的增量编译都会自动处理。坏处是第三方源码会被打进你的工程里如果你的项目有严格的 SDK 合规要求那就要用下面这种预编译库的方式。4.2 预编译静态库find_library 与宏定义如果你的环境里已经有一个编译好的sqlite3.lib就不需要add_subdirectory了用find_library去定位库文件find_library(SQLITE3_LIB NAMES sqlite3 PATHS D:/libs/sqlite3/lib ) if(NOT SQLITE3_LIB) message(FATAL_ERROR sqlite3.lib not found) endif()然后在add_executable后面这样链接add_executable(hello_demo main.cpp) target_link_libraries(hello_demo PRIVATE ${SQLITE3_LIB}) target_compile_definitions(hello_demo PRIVATE SQLITE_STATIC SQLITE_OMIT_LOADEXTENSION)SQLITE_STATIC这个宏在 MSVC 环境下特别重要SQLite 的源码头文件里会根据它决定要不要做动态导入导出。如果静态链接却不定义这个宏链接阶段会报一堆unresolved external symbol __imp_sqlite3_open之类的错误比较新手的做法能排查到怀疑人生。4.3 构建命令和运行验证在D:\demo\hello\build里执行cmake -G Visual Studio 15 2017 Win64 .. cmake --build . --config Debug构建完成后可执行文件在build\Debug\hello_demo.exe运行它如果输出hello from cmake 3.10说明整个链路是通的。到这里你已经把一个真实的第三方 C 库接进了自己的 CMake 工程后面无论是接 OpenCV 还是接 Qt配置逻辑都是这个套路要么源码进来参与编译要么预编译库通过 find 工具找到然后链接。5. 老版本避坑实录Qt、路径、策略和生成器的翻车现场5.1 现象cmake-gui 配置后 VS 打开说找不到工程文件我用 3.10 给一个课程设计配过工程刚开始图省事把 build 目录建在了源码目录里面结果cmake -G Visual Studio 15 2017 Win64 ..之后生成的.sln路径又深又乱VS 打开后偶尔会报找不到项目文件。原因很简单构建目录放在源码目录里CMake 生成的相对路径会互相纠缠尤其源码本身还带中文目录名的时候生成器在写路径时对非 ASCII 字符处理得很笨。解决方式是把 build 目录放在源码目录同级的外部比如源码在D:\demo\hellobuild 放在D:\demo\hello_build。5.2 现象C:/Qt/Qt5.9.4/5.9.4/msvc2017_64/lib/cmake/Qt5/Qt5Config.cmake 报错这是实际群里问得最多的一条CMake Error at C:/Qt/Qt5.9.4/5.9.4/msvc2017_64/lib/cmake/Qt5/Qt5Config.cmake:9。原因基本是find_package(Qt5)找不到 Qt 的路径而 3.10 版本的 find_package 对 Qt5 的搜索策略比较死板不会自动去找C:/Qt这种常见安装位置。解决方式是在配置时手动指定Qt5_DIRcmake -G Visual Studio 15 2017 Win64 -DQt5_DIRC:/Qt/Qt5.9.4/5.9.4/msvc2017_64/lib/cmake/Qt5 ..注意这里的路径指向lib/cmake/Qt5不是 Qt 的根目录。如果项目里同时用了 Qt5Core、Qt5WidgetsCMake 会根据这个路径自动找到其他模块。5.3 现象配置时报 CMP0048 策略警告老版本 CMake 在工程里写了project(HelloDemo VERSION 1.0)但没写版本策略时会弹出一条Policy CMP0048 is not set的警告。原因是 CMP0048 这个策略在 3.10 里默认还是 OLD 行为project()的 VERSION 参数不会被完整记录导致后面的版本号判断逻辑出错。解决方式是在cmake_minimum_required之后显式写一行cmake_policy(SET CMP0048 NEW)从 CMake 3.0 开始引入的策略在 3.10 年代经常要手动设置到了 4.x 版本默认值才完全翻转。新手遇到这个警告可以忽略但如果后面要做版本号判断或者生成安装包最好还是显式设置。5.4 现象VC 编译器检测失败卡在 CMakeDetermineCompilerID.cmake老机器上经常出新问题最常见的是 VS2017 装了但没勾选“使用 C 的桌面开发”工作负载cl.exe根本不在环境里。CMake 这时候会在 configure 阶段卡在CMakeDetermineCompilerID.cmake附近日志里看不到具体错误。解决方式分两步先在“开始菜单 → Visual Studio 2017 → x64 Native Tools Command Prompt”里执行cl确认编译器存在再用那个终端跑 CMake而不是用普通 PowerShell。如果cl都没有回去用 Visual Studio Installer 补 C 工具链。5.5 现象Ninja 生成器下路径带空格导致构建失败3.10 版本对路径空格的容忍度比新版本差不少用-G Ninja生成器时如果源码目录或构建目录里带空格构建阶段会报ninja: error: unknown platform之类的怪错但同样的工程换成 VS 生成器却能通过。原因出在 3.10 年代的 Ninja 生成器对路径转义做得不够完善。解决方式是把整个工程挪到纯英文无空格路径下比如D:\dev\demo而不是D:\我的 文档\demo。6. 把 cmake-gui 当调试器用缓存、搜索和生成器切换6.1 配置窗口里的缓存区先读再改老版本 3.10 的 cmake-gui 界面和现在差别不大左边是源码目录和构建目录中间一大块是缓存变量列表下面两个按钮Configure和Generate。很多人不知道中间那些变量是怎么来的其实它们来自CMakeCache.txt文件每次Configure都会重新计算这些值。第一次点Configure后会弹出生成器选择框这里选错后面全白搭VS2017 工程必须选Visual Studio 15 2017 Win64。配置完如果变量区域里有红色高亮项说明某个必填变量没找到值先解决红色项再点 Generate。6.2 从缓存里找依赖线索搜索框的用法cmake-gui 中间变量区的搜索框不是摆设它支持大小写不敏感过滤。比如编译 OpenCV 时找不到 zlib在搜索框输入ZLIB缓存里所有ZLIB_LIBRARY、ZLIB_INCLUDE_DIR都会列出来值如果显示为NOTFOUND说明 find_package 没找到它你就要手动从展开的路径选择器里指向正确的.lib和头文件目录。这个过程本质上是替你在缓存里手动补依赖和命令行-DZLIB_LIBRARY...的效果完全等价。我一般查依赖路径的优先级顺序是先搜索框过滤再看值是不是NOTFOUND最后才去查 CMakeLists 里的 find 指令大多数问题在第二步就能定案。6.3 切换生成器清缓存、重选、再 Configure在 cmake-gui 里切换生成器不像下拉框切一下那么快底层逻辑是 CMake 的缓存里记录着生成器类型直接改很难生效。正确操作是关闭 cmake-gui删掉构建目录里的CMakeCache.txt和CMakeFiles文件夹重新打开后选新的生成器再走一遍 Configure。这个习惯我后来也用在了命令行上任何诡异的生成器行为都先删缓存再重新 configure不跟它较劲。6.4 一个有用的习惯从 configure 日志里找线索3.10 的 cmake-gui 底部的日志面板会记录每次 configure 的完整输出报错信息就藏在其中。比如编译器识别失败日志里会留下CMAKE_CXX_COMPILER的实际路径和失败原因Qt5 找不到日志会列出它尝试过的所有路径。我当时帮人配置一个 OpenCV 工程折腾两小时以为是版本问题最后在日志里看到CMAKE_PREFIX_PATH被项目里的 CMakeLists 主动重置成了空值导致 Qt5 无论如何都搜不到。从那以后我每次配置新机器的 CMake 环境都强制走一遍清缓存、看完整日志、搜索变量这三步不猜不看日志直接重试最容易浪费时间。希望帮到你。本文还有配套的精品资源点击获取