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