簡(jiǎn)介《CMake實(shí)戰(zhàn).pdf》是一份面向 C/C 開(kāi)發(fā)者的 CMake 入門(mén)與進(jìn)階學(xué)習(xí)資料重點(diǎn)解決跨平臺(tái)構(gòu)建、大型項(xiàng)目組織和依賴(lài)庫(kù)接入問(wèn)題。內(nèi)容從 CMake 的背景、安裝與基本語(yǔ)法講起依次覆蓋 Hello World 示例、靜態(tài)庫(kù)與動(dòng)態(tài)庫(kù)構(gòu)建、外部共享庫(kù)與頭文件搜索路徑、常用變量與常用指令并通過(guò) FindCURL 和自定義 FindHello 模塊演示模塊化查找與鏈接方法末尾還給出多目錄模板適合想系統(tǒng)上手 CMake 的讀者邊讀邊練。在此基礎(chǔ)上資料還梳理了 PROJECT、ADD_EXECUTABLE、ADD_LIBRARY、INSTALL、FIND_PACKAGE 等關(guān)鍵指令以及 CMAKE_INCLUDE_PATH/CMAKE_LIBRARY_PATH 環(huán)境變量的用法能幫助讀者看懂并編寫(xiě) CMakeLists.txt。資源為單份 PDF 電子書(shū)共 1 個(gè) pdf 文件壓縮包大小約 998KB下載后可直接閱讀或打印便于離線學(xué)習(xí)目前已有 980 人學(xué)習(xí)下載。通過(guò)這份資料可快速建立對(duì) CMake 構(gòu)建流程和模塊機(jī)制的體系化認(rèn)識(shí)減少多平臺(tái)編譯時(shí)的試錯(cuò)成本。1. CMake實(shí)戰(zhàn)一份構(gòu)建配置筆記最該先弄懂的不是語(yǔ)法而是“什么時(shí)候執(zhí)行”C/C 項(xiàng)目的痛點(diǎn)往往不在寫(xiě)代碼而在“怎么把編譯規(guī)則說(shuō)清楚”同一套源碼到了 Windows 要用 Visual Studio在 Linux 上走 Ninja進(jìn) CI 又換成容器里的 GCCMakefile 寫(xiě)得再用心也架不住平臺(tái)差異。CMake 解決的正是這個(gè)問(wèn)題——把路徑、編譯選項(xiàng)、依賴(lài)關(guān)系用聲明式配置寫(xiě)好再由它生成對(duì)應(yīng)平臺(tái)的構(gòu)建腳本。對(duì)于常年面對(duì)多依賴(lài)工程、又不想被 IDE 綁定的人CMake 是事實(shí)標(biāo)準(zhǔn)也是繞不開(kāi)的一課。像《CMake實(shí)戰(zhàn)》這類(lèi)筆記開(kāi)局不會(huì)先講變量語(yǔ)法而是從“最小可跑工程”起步讓讀者先看到產(chǎn)出物再回去理解工具鏈。下面我會(huì)按“先立框架、再給可抄配置、最后填坑”的順序把整條鏈路拆開(kāi)講。2. 先吃透“配置 - 生成 - 構(gòu)建”三個(gè)階段CMakeLists.txt 才不是黑匣子2.1 三個(gè)階段各負(fù)責(zé)什么弄錯(cuò)的代價(jià)往往是一整天很多新手把 CMake 當(dāng)成編譯器以為執(zhí)行 cmake 命令就等于編完了。實(shí)際上 cmake 只是“構(gòu)建系統(tǒng)的生成器”它讀出 CMakeLists.txt 中的聲明經(jīng)過(guò)一次配置configure生成一份具體的構(gòu)建腳本generate最后由 make、ninja 或 Visual Studio 去執(zhí)行真正的編譯鏈接任務(wù)。三個(gè)階段職責(zé)完全不同。配置階段做的是“求值”解析 CMakeLists.txt、處理 if/函數(shù)調(diào)用、展開(kāi)你自定義的變量并把結(jié)果落盤(pán)到構(gòu)建目錄的 CMakeCache.txt 里。生成階段則基于配置的結(jié)果把 target 轉(zhuǎn)換成對(duì)應(yīng)生成器的項(xiàng)目文件或 Makefile/Ninja 文件。構(gòu)建階段不歸 CMake 管它調(diào)用的是底層的構(gòu)建工具。區(qū)分這三個(gè)階段不是摳概念。典型翻車(chē)場(chǎng)景是你在 CMakeLists.txt 里寫(xiě)了 set(CMAKE_CXX_STANDARD 17)發(fā)現(xiàn)沒(méi)生效原因可能是拼寫(xiě)錯(cuò)誤或位置不對(duì)被后面的 project() 覆蓋也可能因?yàn)榫彺胬镆延信f值cmake 認(rèn)為“沒(méi)有變化”而跳過(guò)重新生成。不理解“配置是一次求值、結(jié)果進(jìn)了緩存”這個(gè)前提排錯(cuò)時(shí)就會(huì)在三個(gè)階段之間反復(fù)折騰。我一般建議新項(xiàng)目第一步就用這種區(qū)分方式審視構(gòu)建流程每次改 CMakeLists.txt 后先觀察配置階段是否真的重新運(yùn)行再去看生成的 build.ninja 或 Makefile 是否有變化最后才懷疑編譯器。把三層的責(zé)任搞清楚構(gòu)建問(wèn)題就縮小了一半。命令行也有相應(yīng)的調(diào)試手段。配置時(shí)加 --trace 可以看到每條 CMake 語(yǔ)句的執(zhí)行順序與變量值--trace-expand 會(huì)把變量替換后的真實(shí)內(nèi)容打出來(lái)。生成后如果懷疑生成的構(gòu)建腳本有問(wèn)題直接打開(kāi) build 目錄里的 build.ninja 或 Makefile 查具體規(guī)則即可。這些都屬于“先確認(rèn)是哪一層出了錯(cuò)”再?zèng)Q定要不要?jiǎng)釉创a。2.2 最小可用的 CMakeLists.txt四個(gè)基本語(yǔ)句與“目標(biāo)導(dǎo)向”的配置先看一個(gè)最小的 C 可執(zhí)行工程。目錄里只有 main.cpp、include/ 和 CMakeLists.txt配置代碼不超過(guò)十行cmake_minimum_required(VERSION 3.16) project(cmake_practice VERSION 1.0.0 LANGUAGES CXX) add_executable(app main.cpp) target_compile_features(app PRIVATE cxx_std_17) target_include_directories(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include )cmake_minimum_required 不只是一個(gè)版本檢查它還決定了很多策略policy的默認(rèn)行為比如 CMP0074 是否允許用 CMAKE_PREFIX_PATH 去搜 find_package。project() 設(shè)置項(xiàng)目名、版本號(hào)和啟用的語(yǔ)言LANGUAGES CXX 會(huì)觸發(fā)編譯器探測(cè)這一步產(chǎn)生的編譯器信息會(huì)進(jìn)入緩存。add_executable 定義了一個(gè)可執(zhí)行目標(biāo)這是 CMake 3.0 之后的核心抽象一切依賴(lài)、編譯選項(xiàng)、頭文件路徑都掛在 target 上而不是掛在全局。target_compile_features 指定 C 標(biāo)準(zhǔn)它會(huì)為不支持該特性的編譯器直接報(bào)配置錯(cuò)誤比 CMAKE_CXX_STANDARD 的“盡力而為”嚴(yán)格得多。很多人習(xí)慣在頂層 set CMAKE_CXX_STANDARD 17簡(jiǎn)單但作用域是全局的大型項(xiàng)目里某個(gè)子目錄再 set 一次就會(huì)把整個(gè)構(gòu)建帶偏target_compile_features 只影響當(dāng)前 targetPRIVATE 表示這個(gè)編譯特性不傳遞給鏈接到它的下游目標(biāo)。構(gòu)建命令分兩段執(zhí)行cmake -S . -B build -G Ninja cmake --build build --target app -j 8第一段完成配置和生成-S 指源碼目錄-B 指構(gòu)建目錄-G 選生成器。第二段才真正進(jìn)入構(gòu)建--target 指定構(gòu)建哪個(gè)目標(biāo)-j 控制并行任務(wù)數(shù)。執(zhí)行第二次 cmake -S . -B build 時(shí)如果 CMakeLists 沒(méi)變化CMake 會(huì)提示“No need to regenerate”直接復(fù)用已有構(gòu)建文件這就是觀察“配置和構(gòu)建分離”最直觀的入口。2.3 變量、緩存和 target配置的三個(gè)核心對(duì)象除語(yǔ)法外CMake 的配置體系由三件套構(gòu)成變量、緩存和目標(biāo)。普通變量只在當(dāng)前 CMakeLists 展開(kāi)過(guò)程里有效用 set() 定義緩存變量則寫(xiě)入 CMakeCache.txt下次 configure 仍然存在用 -D 傳參時(shí)設(shè)置的就是緩存變量。target 是另一個(gè)維度它描述“構(gòu)建什么”和“怎么和別的 target 關(guān)聯(lián)”。理解這三者的關(guān)系最常用到的參數(shù)可以看這張表參數(shù)作用使用場(chǎng)景-S指定源碼根目錄替代舊的 cd cmake .. 寫(xiě)法-B指定構(gòu)建目錄讓源碼目錄保持干凈-G指定生成器Ninja / Visual Studio / Unix Makefiles-D設(shè)置緩存變量覆蓋 CMAKE_BUILD_TYPE、依賴(lài)路徑等--build調(diào)用底層工具構(gòu)建替代直接敲 make 或 ninja一個(gè)典型用法是臨時(shí)切構(gòu)建類(lèi)型cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPERelWithDebInfoCMAKE_BUILD_TYPE 是單配置生成器Ninja、Unix Makefiles才需要顯式設(shè)置的變量Visual Studio 屬于多配置生成器會(huì)在 IDE 里按 Debug/Release 分別生成不依賴(lài)這個(gè)變量。這也是很多人把項(xiàng)目從 Linux 挪到 Windows 后發(fā)現(xiàn) -DCMAKE_BUILD_TYPE 不生效的原因——不是寫(xiě)錯(cuò)了而是生成器的配置模型不同。還有一個(gè)容易被忽略的細(xì)節(jié)普通變量名區(qū)分大小寫(xiě)但 CMake 的緩存變量在命令行里通常是全大寫(xiě)。用 set(CMAKE_BUILD_TYPE Debug) 和用 -DCMAKE_BUILD_TYPEDebug 的效果不同前者只改當(dāng)前配置過(guò)程后者能跨 configure 持久化。調(diào)試時(shí)不確定變量是誰(shuí)設(shè)的可以直接看 build/CMakeCache.txt里面記錄了每個(gè)緩存變量的來(lái)源和當(dāng)前值。3. 第三方依賴(lài)接入find_package 查找、FetchContent 拉源碼和 CMake GUI 調(diào)參3.1 find_package 的兩種模式MODULE 與 CONFIG以及“找到”的含義第三方庫(kù)集成是 CMake 實(shí)戰(zhàn)里最耗時(shí)間的部分。許多人的第一反應(yīng)是手動(dòng)加 include 路徑和庫(kù)文件路徑但這會(huì)退化成一個(gè)又一個(gè) -I 和 -L換臺(tái)機(jī)器全部失效。CMake 的標(biāo)準(zhǔn)做法是用 find_package而理解它有兩種查找模式能省掉不少排查時(shí)間。MODULE 模式由 CMake 自帶或項(xiàng)目提供的 FindXXX.cmake 腳本執(zhí)行查找腳本里封裝了頭文件路徑、庫(kù)文件路徑和版本判斷邏輯CONFIG 模式由庫(kù)安裝時(shí)自帶的 XXXConfig.cmake 提供信息?，F(xiàn)代庫(kù)基本都走 CONFIG 模式因?yàn)榘惭b時(shí)能把自己的目標(biāo)、編譯選項(xiàng)、接口依賴(lài)全部導(dǎo)出。find_package(OpenCV REQUIRED) target_link_libraries(app PRIVATE ${OpenCV_LIBS})這里要分清find_package 找到的并不一定是“庫(kù)文件”可能是一組變量也可能是一個(gè)導(dǎo)入目標(biāo)imported target。老庫(kù)習(xí)慣導(dǎo)出變量比如 OpenCV_LIBS、OpenCV_INCLUDE_DIRS新庫(kù)會(huì)導(dǎo)出 OpenCV::core 這樣的命名空間目標(biāo)鏈接它就能自動(dòng)帶上 include 目錄和傳遞依賴(lài)。判斷庫(kù)支持哪種方式可以看安裝目錄下有沒(méi)有 xxx-config.cmake 或 xxxConfig.cmake。find_package 默認(rèn)按一套搜索順序查找最常用到的修正手段是指定搜索起點(diǎn)-DCMAKE_PREFIX_PATH/path/to/libroot。這個(gè)緩存變量同時(shí)影響 CONFIG 模式下的 XXXConfig.cmake 查找路徑以及 find_path/find_library 的搜索范圍。如果你的庫(kù)裝在非標(biāo)準(zhǔn)位置先設(shè)這個(gè)變量比逐個(gè)改 CMAKE_INCLUDE_PATH 和 CMAKE_LIBRARY_PATH 要省事得多。3.2 沒(méi)有系統(tǒng)庫(kù)可找時(shí)FetchContent 把依賴(lài)源碼直接拉進(jìn)構(gòu)建系統(tǒng)里沒(méi)裝這個(gè)庫(kù)或者想要保證所有人用的依賴(lài)版本一致常見(jiàn)做法是 FetchContent。它的特點(diǎn)是把依賴(lài)源碼當(dāng)作主工程的一部分參與構(gòu)建所有 target 在同一個(gè)構(gòu)建圖里能共享編譯緩存和編譯選項(xiàng)這是它目前比 ExternalProject 更受歡迎的原因。include(FetchContent) FetchContent_Declare( my_lib GIT_REPOSITORY https://your-git-host/team/my_lib.git GIT_TAG v1.2.0 GIT_SHALLOW TRUE ) FetchContent_MakeAvailable(my_lib) target_link_libraries(app PRIVATE my_lib)FetchContent_Declare 只是登記依賴(lài)信息和獲取方式真正觸發(fā)下載和構(gòu)建的是 FetchContent_MakeAvailable。它會(huì)檢查依賴(lài)是否已經(jīng)被某個(gè)父工程定義沒(méi)有才執(zhí)行下載、解包和 add_subdirectory。GIT_SHALLOW TRUE 表示淺克隆只取指定 tag 的代碼能顯著減少下載量如果需要依賴(lài)的完整提交歷史去做子模塊聯(lián)動(dòng)就不要開(kāi)這個(gè)選項(xiàng)。FetchContent 的坑主要在下載階段編譯機(jī)沒(méi)外網(wǎng)時(shí)配置會(huì)卡在拉取代碼。常見(jiàn)做法是把依賴(lài)源碼先打包放到內(nèi)網(wǎng) Git 或本地文件路徑GIT_REPOSITORY 換成 file:// URL或者用 PATCH_COMMAND 在源碼落地后做本地定制。依賴(lài)下載后被緩存到構(gòu)建目錄下的 _deps 子目錄刪掉 build 目錄就等于刪掉所有依賴(lài)源碼下次全量拉取離線環(huán)境里這一下會(huì)非常痛。3.3 用 CMake GUI 或 -D 參數(shù)管理緩存變量一次完整的調(diào)參路徑CMake 自帶圖形工具 cmake-gui很多人以為它只是給 Windows 用戶(hù)填路徑用的其實(shí)它不是用來(lái)寫(xiě) CMakeLists 的而是用來(lái)“一次性查看和修改緩存變量”的。終端下每次傳 -D 太長(zhǎng)、記不住變量名時(shí)GUI 的價(jià)值就很明顯點(diǎn) Configure 選生成器和編譯器左側(cè)按分組列出所有緩存變量改完再點(diǎn) Generate。整個(gè)過(guò)程其實(shí)就是配置階段的圖形化版本底層改的還是 CMakeCache.txt。cmake -S . -B build -G Ninja \ -DCMAKE_BUILD_TYPEDebug \ -DCMAKE_PREFIX_PATH$(pwd)/third_party_install \ -DMY_FEATURE_FLAGON這四條是命令行調(diào)參最常見(jiàn)組合指定源碼和構(gòu)建目錄、選生成器、設(shè)構(gòu)建類(lèi)型、告訴 CMake 去哪里找第三方安裝。其中 MY_FEATURE_FLAGON 這種自定義緩存變量在 CMakeLists 里一般需要配合 option() 或 cache 聲明否則 -D 傳一個(gè)未聲明的變量CMake 只是把它放進(jìn)緩存CMakeLists 里讀不到也不會(huì)報(bào)錯(cuò)——這是很多人“設(shè)了變量但沒(méi)反應(yīng)”的真相之一。CMake GUI 和命令行混用時(shí)要記住緩存是持久化的。GUI 里 Configure 過(guò)之后再跑命令行 -D 覆蓋同名變量最終以最后一次為準(zhǔn)。如果 GUI 里改了變量但 CMakeLists 好像沒(méi)生效先打開(kāi) build/CMakeCache.txt 搜索這個(gè)變量名看是不是在別的位置被 set() 覆蓋了沒(méi)有再考慮刪除緩存重新配置。4. CMake 常見(jiàn)坑與排查緩存不刷新、鏈接失敗、strip 與編譯器混用4.1 頭文件找不到先查 include 目錄是 PUBLIC 還是 PRIVATE現(xiàn)象find_package 和 target_link_libraries 都寫(xiě)了構(gòu)建仍報(bào) fatal error: xxx.h: No such file or directory。原因這個(gè)問(wèn)題九成出在“頭文件目錄沒(méi)有傳播”上。target 的 include 目錄分為 PRIVATE、PUBLIC、INTERFACE 三種可見(jiàn)性PRIVATE 只對(duì)當(dāng)前目標(biāo)可見(jiàn)如果一個(gè)靜態(tài)庫(kù)把依賴(lài)的頭文件目錄配成了 PRIVATE下游目標(biāo)鏈接它時(shí)那些頭文件路徑不會(huì)自動(dòng)出現(xiàn)。另一個(gè)常見(jiàn)場(chǎng)景是第三方庫(kù)的 Config 文件只導(dǎo)出了庫(kù)文件路徑?jīng)]導(dǎo)出它的 include 目錄。解決先查庫(kù)的目標(biāo)是否帶接口頭文件路徑方法是在生成的鏈接規(guī)則里看 include 實(shí)際展開(kāi)結(jié)果更直接的是打開(kāi)庫(kù)自帶的 xxxConfig.cmake搜索 INTERFACE_INCLUDE_DIRECTORIES。沒(méi)有就手動(dòng)補(bǔ)target_include_directories(app PRIVATE ${MY_LIB_INCLUDE_DIR} )但這是打補(bǔ)丁。理想做法是讓依賴(lài)方把 include 目錄作為 INTERFACE 屬性導(dǎo)出或者修改第三方庫(kù)的 CMakeLists 來(lái)修正它的目標(biāo)屬性。4.2 改完 CMakeLists 重新構(gòu)建跑的還是舊規(guī)則現(xiàn)象往 add_executable 里新增了一個(gè)源文件重新執(zhí)行 cmake --build 后新增文件沒(méi)有被編譯進(jìn)產(chǎn)物。原因add_executable 里的源文件列表是在配置階段展開(kāi)的配置過(guò)程檢測(cè)到 CMakeLists 變化會(huì)重新運(yùn)行但前提是 CMake 認(rèn)為“有必要”。如果用的是 file(GLOB) 自動(dòng)收集源文件GLOB 的結(jié)果只在配置時(shí)展開(kāi)一次新增文件不會(huì)觸發(fā)重新配置這是 CMake 里最經(jīng)典的翻車(chē)點(diǎn)。還有一個(gè)隱性原因修改的是 build 目錄里的緩存變量但命令行沒(méi)重新執(zhí)行 configure直接做 --build 時(shí)被生成器跳過(guò)了。解決最穩(wěn)妥的手段是手動(dòng)觸發(fā)一次干凈的配置rm -rf build cmake -S . -B build -DCMAKE_BUILD_TYPEDebug cmake --build build -j 8如果你不想全量重建可以先只刪除 CMakeCache.txt 再重新 configure但依賴(lài)路徑和編譯器信息會(huì)丟失有些變量會(huì)回到默認(rèn)值。對(duì) file(GLOB)如果項(xiàng)目規(guī)?？煽赝扑]顯式列出源文件一定要用 GLOB就在 file() 加 CONFIGURE_DEPENDS讓 CMake 在構(gòu)建時(shí)重新檢查文件列表。代價(jià)是每次構(gòu)建都會(huì)多一步目錄掃描大型項(xiàng)目有明顯開(kāi)銷(xiāo)。4.3 鏈接時(shí)報(bào) undefined reference靜態(tài)庫(kù)鏈接順序和“沒(méi)鏈接進(jìn)來(lái)”是兩回事現(xiàn)象target_link_libraries 里明明加了庫(kù)鏈接階段還是報(bào)一堆未定義符號(hào)而且這些符號(hào)在庫(kù)里確實(shí)存在。原因靜態(tài)庫(kù)的鏈接順序是敏感的。鏈接器從左到右掃描目標(biāo)文件后面的庫(kù)引用前面的符號(hào)才能解析如果庫(kù) B 依賴(lài)庫(kù) A命令行里 B 出現(xiàn)在 A 之前符號(hào)就無(wú)法解析。CMake 的 target_link_libraries 順序會(huì)直接體現(xiàn)在生成鏈接命令里手工調(diào)整順序只是臨時(shí)解法。另一類(lèi)原因是某些庫(kù)不是通過(guò)目標(biāo)鏈接的而是直接寫(xiě)了絕對(duì)路徑路徑本身的格式或庫(kù)類(lèi)型與當(dāng)前編譯器不匹配。解決把依賴(lài)關(guān)系理順按“被依賴(lài)者放后面”的原則排列庫(kù)。不要手寫(xiě) -l 參數(shù)讓 CMake 管理順序。需要看真實(shí)鏈接命令時(shí)加 verbosecmake --build build --verbose這會(huì)打印每個(gè)編譯和鏈接動(dòng)作的完整命令行?？吹?link.txt 內(nèi)容后確認(rèn)所有庫(kù)的順序和依賴(lài)關(guān)系一致。如果確實(shí)存在兩個(gè)靜態(tài)庫(kù)互相引用這種“循環(huán)依賴(lài)”用鏈接器的 start-group/end-group 兜底但這是最后的處理手段正常項(xiàng)目應(yīng)該通過(guò)重構(gòu)目標(biāo)拆分來(lái)避免。4.4 發(fā)布時(shí)想 strip 符號(hào)結(jié)果把調(diào)試信息也全刪了現(xiàn)象在 CMakeLists 里加了一句 set(CMAKE_CXX_FLAGS_RELEASE -s)Release 產(chǎn)物變小了但需要調(diào)試線上問(wèn)題時(shí)backtrace 里的函數(shù)名全部變成了地址。原因-s 是給鏈接器的 strip 選項(xiàng)等于在鏈接階段直接剝離符號(hào)表。把它塞進(jìn) CMAKE_CXX_FLAGS_RELEASE會(huì)讓所有 Release 目標(biāo)無(wú)差別地被 strip包括那些還想留符號(hào)做調(diào)試的庫(kù)。更麻煩的是 Debug 構(gòu)建通常不帶這個(gè)參數(shù)導(dǎo)致 Debug 和 Release 產(chǎn)物的可調(diào)試性差異巨大。解決在目標(biāo)級(jí)別精確控制而不是設(shè)置全局變量if(CMAKE_STRIP) add_custom_command(TARGET app POST_BUILD COMMAND ${CMAKE_STRIP} $TARGET_FILE:app COMMENT Stripping symbols from app ) endif()CMake 的 CMAKE_STRIP 變量會(huì)在初始化階段探測(cè)到工具鏈自帶 strip 程序。用 add_custom_command 掛在目標(biāo)構(gòu)建完成后命令里用生成器表達(dá)式 $TARGET_FILE:app 獲取實(shí)際產(chǎn)物路徑。這樣只有指定目標(biāo)會(huì)被處理而且只在對(duì)應(yīng)構(gòu)建類(lèi)型里生效。如果要把這個(gè)行為綁定到 install 流程可以用 install(CODE) 嵌一段 strip 調(diào)用確保被打包的是剝離過(guò)符號(hào)的可執(zhí)行文件。血淚經(jīng)驗(yàn)是strip 和調(diào)試信息的取舍應(yīng)該按目標(biāo)劃分而不是按構(gòu)建類(lèi)型一刀切。4.5 新版 CMake 語(yǔ)法用不了apt 裝的版本太舊離線環(huán)境怎么裝新版現(xiàn)象項(xiàng)目 CMakeLists 里用了 FetchContent或者 cmake_minimum_required(VERSION 3.16) 直接報(bào)錯(cuò)提示當(dāng)前 cmake 版本是 3.10。原因apt 倉(cāng)庫(kù)里的 CMake 版本跟隨系統(tǒng)發(fā)行版Ubuntu 18.04 默認(rèn)就是 CMake 3.10 左右很多現(xiàn)代語(yǔ)法和模塊不可用。這不是配置寫(xiě)錯(cuò)而是工具鏈版本不足。解決CMake 官方提供預(yù)編譯的二進(jìn)制包適合在線環(huán)境或離線拷貝安裝。離線安裝的常見(jiàn)做法是在能聯(lián)網(wǎng)的機(jī)器上下載對(duì)應(yīng) Linux 平臺(tái)的 tar.gz 包拷到目標(biāo)機(jī)器后解壓到 /opt然后把 bin 目錄加進(jìn) PATH。版本選擇上優(yōu)先看 cmake_minimum_required 要求再留一點(diǎn)余量不要追最新版。tar -xzf cmake-x.y.z-linux-x86_64.tar.gz -C /opt export PATH/opt/cmake-x.y.z-linux-x86_64/bin:$PATH cmake --version這個(gè)安裝方式不依賴(lài)發(fā)行版包管理器也不污染系統(tǒng)目錄比較適合同一臺(tái)機(jī)器上維護(hù)多個(gè)項(xiàng)目、不同 CMake 版本的需求。注意檢查 PATH 優(yōu)先級(jí)如果系統(tǒng)自帶 cmake 在 /usr/binexport PATH 要放在 /usr/bin 前面重開(kāi)終端后不生效說(shuō)明 export 沒(méi)有寫(xiě)進(jìn) shell 配置。在線環(huán)境里也有 pip 安裝 CMake 的方式適合想隔離在虛擬環(huán)境里的場(chǎng)景但要注意很多工程腳本默認(rèn)調(diào)用的仍是系統(tǒng) cmake。5. 把構(gòu)建配置沉淀成工程資產(chǎn)Presets、compile_commands 與可復(fù)現(xiàn)構(gòu)建5.1 一次配置團(tuán)隊(duì)共用CMakePresets.json項(xiàng)目里每臺(tái)機(jī)器、每個(gè) IDE 都在用不同的命令行參數(shù)時(shí)溝通成本很高。CMake 3.21 之后可以用 CMakePresets.json 把常用配置固定下來(lái)把 -D、-G、構(gòu)建目錄這些參數(shù)全部收進(jìn)倉(cāng)庫(kù)統(tǒng)一入口。下面是一份最小可用的配置{ version: 3, cmakeMinimumRequired: { major: 3, minor: 21, patch: 0 }, configurePresets: [ { name: dev, generator: Ninja, binaryDir: ${sourceDir}/build/dev, cacheVariables: { CMAKE_BUILD_TYPE: Debug, CMAKE_EXPORT_COMPILE_COMMANDS: ON } } ], buildPresets: [ { name: dev, configurePreset: dev, jobs: 8 } ] }使用方式變成兩行命令cmake --preset dev cmake --build --preset dev團(tuán)隊(duì)里所有成員用同一個(gè) preset 名構(gòu)建目錄、緩存變量、生成器全部一致。比在 README 里寫(xiě)一長(zhǎng)串命令更不容易出錯(cuò)。同一個(gè) preset 可以派生出 debug、release、asan 等多個(gè)變體用 inherits 字段復(fù)用公共配置避免每個(gè)開(kāi)發(fā)者維護(hù)自己的命令歷史。5.2 驗(yàn)證構(gòu)建規(guī)律compile_commands 與 ccacheCMAKE_EXPORT_COMPILE_COMMANDS 開(kāi)啟后構(gòu)建目錄下會(huì)生成 compile_commands.json里面是每個(gè)源文件的真實(shí)編譯命令。這份文件對(duì) clangd、ccls 這類(lèi)語(yǔ)言服務(wù)器很有價(jià)值IDE 或編輯器能據(jù)此做跳轉(zhuǎn)和補(bǔ)全而不用自己解析 CMake 配置。驗(yàn)證構(gòu)建是否可復(fù)現(xiàn)我的習(xí)慣是每周至少一次從零構(gòu)建刪除 build 目錄后按同一份 preset 重新配置、構(gòu)建確認(rèn)不會(huì)出現(xiàn)只在“增量構(gòu)建”階段才暴露的臟依賴(lài)問(wèn)題。保持這個(gè)習(xí)慣后我發(fā)現(xiàn)不少問(wèn)題其實(shí)是增量構(gòu)建條件下沒(méi)暴露出來(lái)的某個(gè)目標(biāo)依賴(lài)了過(guò)期產(chǎn)物、某個(gè)頭文件沒(méi)被正確聲明為依賴(lài)、生成器表達(dá)式只在干凈構(gòu)建時(shí)求值正確。配合 ccache 能緩解“全量重建耗時(shí)”的顧慮。配置時(shí)指定編譯器 launcherCMake 會(huì)把它插入到每次編譯命令前執(zhí)行cmake -S . -B build -DCMAKE_CXX_COMPILER_LAUNCHERccacheccache 命中后即使刪了 build 目錄也能復(fù)用同一份編譯緩存全量重建的時(shí)間能被壓到很小的范圍。驗(yàn)證的時(shí)候先查 ccache -s 的命中率再判斷哪些目標(biāo)適合做 clean-first。經(jīng)過(guò)這些年踩坑我現(xiàn)在的習(xí)慣是先跑 --verbose 看真實(shí)編譯命令再?zèng)Q定要不要?jiǎng)?CMakeLists先把構(gòu)建配置凍結(jié)成 preset再把干凈構(gòu)建納入每周節(jié)奏。構(gòu)建配置應(yīng)該像代碼一樣被審閱和維護(hù)而不是想起來(lái)才清理一次。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取