干這行這些年每天繞不開的就是 cmake 構(gòu)建這套流程。不管你是接手別人的 C/C 項(xiàng)目還是自己從零搭一個(gè)庫第一步幾乎都是看 CMakeLists.txt 寫得怎么樣。說實(shí)話cmake 的上手門檻并不高但真正用明白的人不多不少人停留在“能跑就行”的階段一碰到跨平臺、多目錄、第三方依賴就抓瞎。這篇東西不打算做成文檔式的羅列我更想以一個(gè)實(shí)際用 cmake 構(gòu)建過不少項(xiàng)目的從業(yè)者身份把核心機(jī)制、常見玩法、以及那些文檔里不會寫的坑一次性講透。無論你是剛接觸構(gòu)建的新手還是已經(jīng)在用但經(jīng)常被奇奇怪怪的 CMake Error 折磨的老手這篇文章應(yīng)該都能給你一些參考。1. cmake到底解決了什么問題——先搞清它在構(gòu)建鏈中的位置1.1 從手寫 Makefile 到 cmake 的過渡很多人的困惑從名字開始。cmake 不是一個(gè)編譯器也不是一個(gè)獨(dú)立的構(gòu)建工具它是一個(gè)“構(gòu)建系統(tǒng)的生成器”。換句話說你自己不直接干活而是把活派給底層的構(gòu)建系統(tǒng)去干。這個(gè)底層構(gòu)建系統(tǒng)可以是 Unix 平臺的 Makefile可以是 Ninja也可以是 Windows 上的 Visual Studio 工程。在沒有 cmake 的年代一個(gè)跨平臺 C/C 項(xiàng)目要同時(shí)支持 Linux 和 Windows你需要維護(hù)兩套甚至三套構(gòu)建腳本Linux 下寫 MakefileWindows 下維護(hù) .vcxprojmacOS 下甚至還要考慮 Xcode 工程。一旦代碼文件變了或者新增了目錄所有平臺下的構(gòu)建腳本都要同步改一遍這幾乎是噩夢。我第一次真正被 Makefile 折磨到崩潰是在一個(gè)同時(shí)依賴 OpenSSL、zlib 和幾十個(gè)內(nèi)部模塊的通信項(xiàng)目里。頭文件路徑、鏈接庫順序、編譯宏全部要手寫維護(hù)。某次為了加一個(gè)新模塊改了 Makefile 里的依賴關(guān)系結(jié)果漏了一個(gè)頭文件路徑編譯全過了運(yùn)行時(shí)崩潰查了整整一天才定位到是構(gòu)建腳本的問題。從那時(shí)起我就決定在新項(xiàng)目里統(tǒng)一用 cmake至少不用再為每臺機(jī)器的構(gòu)建環(huán)境重復(fù)造輪子。1.2 cmake 和 makefile 的本質(zhì)區(qū)別這里直接說結(jié)論。Makefile 是面向“當(dāng)前這棵樹”的構(gòu)建規(guī)則它告訴 make 命令如何編譯、如何鏈接、文件之間依賴關(guān)系怎樣。它是具體的、不可移植的。而 cmake 的 CMakeLists.txt 是更高一層的抽象它描述的是項(xiàng)目的結(jié)構(gòu)與目標(biāo)然后由 cmake 替你生成對應(yīng)平臺的 Makefile 或 IDE 工程。用生活化的類比來說Makefile 像是你雇了一個(gè)工人你直接告訴他一磚一瓦怎么砌。cmake 則像是一個(gè)項(xiàng)目經(jīng)理你只告訴他這里要一棟樓、那里要一個(gè)花園具體用哪臺吊車、哪個(gè)施工隊(duì)由他根據(jù)現(xiàn)場情況去安排。兩者直觀對比一下對比項(xiàng)MakefileCMake位置構(gòu)建規(guī)則文件生成構(gòu)建規(guī)則的文件跨平臺能力基本綁定 Unix make支持 Makefile/Ninja/VS/Xcode 等多類生成器依賴管理手動維護(hù)內(nèi)置 find_package、FetchContent 等機(jī)制IDE 集成差基本靠命令行VS、CLion、VSCode 都原生支持學(xué)習(xí)成本語法簡單但組織繁瑣入門容易進(jìn)階需理解 target 與生成器表達(dá)式適合規(guī)模小項(xiàng)目、個(gè)人工具中大型項(xiàng)目、團(tuán)隊(duì)協(xié)作、跨平臺這不是說 Makefile 一無是處它就是 cmake 的下游產(chǎn)物之一很多時(shí)候你還會直接讀到它。但如果你要新建一個(gè)項(xiàng)目或者維護(hù)一個(gè)需要長期演進(jìn)的代碼庫選 cmake 幾乎是現(xiàn)在行業(yè)里的默認(rèn)答案。1.3 構(gòu)建鏈條中的兩個(gè)階段理解 cmake 一定要先分清兩個(gè)階段。第一個(gè)階段是配置階段。你執(zhí)行cmake -S . -B buildcmake 會讀取 CMakeLists.txt把里面的邏輯展開成一套具體的構(gòu)建文件。這個(gè)階段會做很多“探路”工作檢查編譯器是否存在、檢測系統(tǒng)庫、嘗試編譯并運(yùn)行一段小測試代碼來驗(yàn)證某個(gè)特性然后把結(jié)果緩存下來。第二個(gè)階段才是真正的構(gòu)建階段。你執(zhí)行cmake --build buildcmake 調(diào)用底層構(gòu)建系統(tǒng)比如 make 或 ninja執(zhí)行實(shí)際的編譯和鏈接。這里不再需要 cmake 去分析你的 CMakeLists.txt它只是作為入口去驅(qū)動底層工具。這個(gè)“兩個(gè)階段”心智模型非常重要。我在實(shí)際工作中見過很多人改完 CMakeLists.txt 只跑cmake --build發(fā)現(xiàn)改動不生效然后開始懷疑人生。實(shí)際上改了 CMakeLists.txt 之后必須重新回到配置階段也就是重跑cmake -S . -B build或者讓 IDE 自動觸發(fā)一次重配置修改才會生效。2. 環(huán)境準(zhǔn)備與第一個(gè) cmake 工程2.1 各平臺安裝 cmake 的方法cmake 的安裝本身相當(dāng)簡單但不同平臺有各自需要注意的地方。Linux 上最常見的做法是用包管理器裝。Ubuntu/Debian 系直接sudo apt install cmake。不過這里有個(gè)坑apt 源里的 cmake 版本通常偏舊。Ubuntu 20.04 自帶的可能還是 3.16 左右的版本很多新特性用不了。如果你的項(xiàng)目要求cmake_minimum_required(VERSION 3.20)甚至更高你需要先確認(rèn)系統(tǒng)源的版本或者使用官方腳本安裝。我個(gè)人實(shí)踐下來更推薦用 pip 安裝pip install cmake。這個(gè)方案的好處是版本新、干凈、不污染系統(tǒng)卸載也方便。Windows 上直接去官方下載安裝包即可。另外也可以用winget install Kitware.CMake裝完就在 PATH 里不需要額外配置。macOS 上則是brew install cmake同樣沒什么坑。安裝完成后驗(yàn)證版本用cmake --version能看到版本號就說明裝好了。這里提醒一句cmake 的版本策略很保守高版本生成的構(gòu)建目錄可以匹配低版本的 cmake但反過來不行。所以如果團(tuán)隊(duì)協(xié)作建議所有人在同一個(gè)主要版本線附近至少不要低于項(xiàng)目里cmake_minimum_required指定的版本。2.2 cmake-gui 什么時(shí)候用得上很多人看到 cmake 第一眼是 cmake-gui 這個(gè)圖形界面。它長得很樸素左邊一堆變量、右邊一堆按鈕實(shí)際上它就是配置階段的圖形化入口。你可以在界面上設(shè)定CMAKE_BUILD_TYPE是 Debug 還是 Release可以指定CMAKE_INSTALL_PREFIX可以勾選各種option定義的功能開關(guān)甚至可以手動添加CMAKE_PREFIX_PATH來告訴 cmake 去哪找某個(gè)依賴庫。那是不是新手就該用 cmake-gui我的看法是能不用就不用。原因很簡單圖形界面的操作不透明你點(diǎn)了一下“Configure”cmake 到底做了什么、生成了什么、為啥某個(gè)變量變成紅色 NOTFOUND它不會告訴你你也不容易記住。相比之下命令行操作直接、可復(fù)現(xiàn)而且這些配置步驟最終都能寫進(jìn)腳本里讓整個(gè)構(gòu)建過程自動化。但 cmake-gui 也不是完全沒用。當(dāng)你在排查一個(gè)復(fù)雜的依賴查找問題時(shí)GUI 里能把所有緩存變量攤開來看比命令行一行行敲cmake -LA要直觀得多。我會在排查問題時(shí)才打開它專門看某個(gè)庫的路徑變量到底被設(shè)置成了什么。2.3 最小工程從零開始不整那些虛的直接寫一個(gè)能跑的 CMakeLists.txt。假設(shè)你的項(xiàng)目就一個(gè)單文件main.cpp那么 CMakeLists.txt 只需要六行cmake_minimum_required(VERSION 3.16) project(FirstDemo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) add_executable(demo main.cpp)逐行說下作用。第一行指定 cmake 最低版本如果本機(jī)版本太舊會直接報(bào)錯。第二行定義工程名并聲明語言只涉及 C。第三和第四行把編譯標(biāo)準(zhǔn)設(shè)為 C17CMAKE_CXX_STANDARD_REQUIRED設(shè)為 ON 表示這是硬性要求編譯器不支持就直接掛掉而不是打一個(gè)警告然后退回去用默認(rèn)標(biāo)準(zhǔn)。第五行創(chuàng)建了一個(gè)名為 demo 的可執(zhí)行目標(biāo)對應(yīng)的源碼是 main.cpp。然后執(zhí)行cmake -S . -B build cmake --build build -j-S指定源碼目錄-B指定構(gòu)建目錄。構(gòu)建目錄和源碼目錄分開是 cmake 的默認(rèn)最佳實(shí)踐所有的中間文件、緩存、生成物都在 build 目錄里不污染源碼樹。構(gòu)建完成之后build目錄下會多出一個(gè)可執(zhí)行文件 demoLinux 下或 demo.exeWindows 下直接./build/demo就能跑。這段流程雖然簡單但它是后面所有高級用法的地基。后面我們聊到的變量、目標(biāo)、依賴查找本質(zhì)上都是在這套基礎(chǔ)上做擴(kuò)展。3. 核心語法與目標(biāo)target設(shè)計(jì)才是現(xiàn)代 cmake 的靈魂3.1 變量、緩存變量與環(huán)境變量cmake 里的變量引用方式很統(tǒng)一用${VAR}。你可以用set來定義變量set(PROJECT_VERSION_MAJOR 1) set(PROJECT_VERSION_MINOR 2) set(PROJECT_VERSION ${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR})這里的變量是普通變量作用域從定義位置到當(dāng)前 CMakeLists.txt 文件結(jié)束或者到子目錄/函數(shù)邊界被覆蓋。真正干活的時(shí)候普通人最常用到的其實(shí)是緩存變量它由配置階段記錄在 CMakeCache.txt 里。你可以在命令行用-D傳入也可以在 CMakeLists.txt 里用option來定義option(ENABLE_TESTS Build unit tests ON)如果用戶在執(zhí)行 cmake 時(shí)用了-DENABLE_TESTSOFF那這個(gè) ON 就不會生效緩存變量優(yōu)先。環(huán)境變量用$ENV{VAR}讀取一般用于讀取系統(tǒng)環(huán)境信息比如$ENV{HOME}但實(shí)踐中不建議在構(gòu)建邏輯里過度依賴環(huán)境變量因?yàn)椴煌该?、不可?fù)現(xiàn)。真正有版本依賴的配置都應(yīng)該寫成 cmake 變量。3.2 以目標(biāo)為核心的寫法PUBLIC/PRIVATE 怎么理解現(xiàn)代 cmake 的核心概念是“目標(biāo)”。目標(biāo)就是add_executable或add_library創(chuàng)建出來的東西你可以把編譯選項(xiàng)、宏定義、頭文件路徑、鏈接庫統(tǒng)統(tǒng)掛在它身上。最關(guān)鍵的語法是三個(gè)target_include_directories(mylib PUBLIC include) target_compile_definitions(mylib PRIVATE DEBUG_MODE1) target_link_libraries(mylib PUBLIC fmt)這里面的PUBLIC、PRIVATE、INTERFACE是最容易繞暈的地方。我提供一個(gè)我常用的理解方式先想象這個(gè)庫自己編譯時(shí)需要什么再想象使用者還需要什么。如果某樣?xùn)|西既被庫自己用、又被子項(xiàng)目用那它一定是 PUBLIC。如果庫自己編譯時(shí)需要、但使用庫的人根本不需要知道那就是 PRIVATE。如果庫編譯時(shí)根本不需要純屬給別人用的那就是 INTERFACE。實(shí)際操作中經(jīng)常有人把所有東西一律寫成 PUBLIC這在單目錄小項(xiàng)目里也許沒什么問題但一旦項(xiàng)目復(fù)雜起來就會發(fā)生“沒必要地強(qiáng)依賴傳播”——比如內(nèi)部用了某個(gè)私有實(shí)現(xiàn)庫結(jié)果把所有依賴這個(gè)庫的消費(fèi)者都帶上了。正確的做法是默認(rèn)從 PRIVATE 開始當(dāng)出現(xiàn)“下游也需要”的明確需求時(shí)才升級為 PUBLIC。3.3 生成器表達(dá)式解決配置差異生成器表達(dá)式是 cmake 里最強(qiáng)大也最容易忽略的語法。它的形態(tài)是$...在配置階段會被求值在不同構(gòu)建類型、不同平臺上產(chǎn)生不同內(nèi)容。最常見的用法是區(qū)分 Debug 和 Release 編譯宏target_compile_definitions(app PRIVATE $$CONFIG:Debug:ENABLE_DEBUG_LOG $$CONFIG:Release:NDEBUG )這行代碼的意思是如果當(dāng)前配置是 Debug 則定義ENABLE_DEBUG_LOG如果是 Release 則定義NDEBUG。在單一配置生成器如 Makefile下這個(gè)宏由CMAKE_BUILD_TYPE決定在多配置生成器如 VS下同一個(gè)構(gòu)建目錄可以隨時(shí)切換 Debug/Release生成器表達(dá)式依然正確生效。單獨(dú)一個(gè)$CONFIG可能看不出多大威力一旦你要區(qū)分平臺$PLATFORM_ID、編譯器$CXX_COMPILER_ID、甚至可以判斷某條依賴是否存在再決定加不加某個(gè)鏈接庫生成器表達(dá)式幾乎成了唯一的優(yōu)雅解法。我用一個(gè)實(shí)際場景來體會它的價(jià)值。之前做一個(gè)跨平臺庫要同時(shí)支持 MSVC 和 GCC有些 warning 只有 MSVC 才會報(bào)有些只有 GCC 才會報(bào)。如果不用生成器表達(dá)式就得針對編譯器寫兩套 if 分支。用了生成器表達(dá)式之后一行搞定target_compile_options(mylib PRIVATE $$CXX_COMPILER_ID:MSVC:/W4 $$CXX_COMPILER_ID:GNU:-Wall -Wextra )這種寫法在 CMakeLists.txt 里顯得極簡而且可擴(kuò)展性極強(qiáng)。4. 一個(gè)典型工程從單文件到多目錄完整落地4.1 目錄設(shè)計(jì)與 CMakeLists 分層隨著項(xiàng)目越來越大單文件 CMakeLists.txt 會變成一團(tuán)亂麻。普遍的做法是分層寫根目錄一個(gè)總控 CMakeLists.txt子目錄各管各的。一個(gè)我常推薦給團(tuán)隊(duì)的目錄結(jié)構(gòu)長這樣project/ ├── CMakeLists.txt ├── src/ │ ├── CMakeLists.txt │ └── main.cpp ├── libs/ │ ├── CMakeLists.txt │ └── core/ │ ├── CMakeLists.txt │ ├── core.cpp │ └── core.h └── tests/ ├── CMakeLists.txt └── test_core.cpp根 CMakeLists.txt 只做幾件事聲明最低版本、項(xiàng)目名、設(shè)置全局編譯選項(xiàng)、然后用add_subdirectory引入子目錄。cmake_minimum_required(VERSION 3.16) project(MyProject LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) add_subdirectory(libs) add_subdirectory(src) add_subdirectory(tests)子目錄的 CMakeLists.txt 各自維護(hù)自己的目標(biāo)。libs/core/CMakeLists.txt大概長這樣add_library(core STATIC core.cpp) target_include_directories(core PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})而src/CMakeLists.txt則負(fù)責(zé)鏈接這個(gè)庫add_executable(myapp main.cpp) target_link_libraries(myapp PRIVATE core)這套做法的最大好處是職責(zé)清晰。根目錄不關(guān)心具體細(xì)節(jié)子目錄不關(guān)心全局配置。新人看到某個(gè)目錄打開這個(gè)目錄的 CMakeLists.txt 就能理解它編譯什么、鏈接什么。另外add_subdirectory天然地把不同目錄的目標(biāo)放進(jìn)同一個(gè)構(gòu)建樹里目標(biāo)名就是你在構(gòu)建系統(tǒng)里可以直接引用的名字不需要手動去拼路徑。4.2 處理好第三方依賴find_package 的兩種模式真實(shí)項(xiàng)目幾乎不可能完全不依賴第三方庫。這時(shí)就要用到find_package。它的使用形態(tài)很統(tǒng)一find_package(OpenCV REQUIRED) target_link_libraries(myapp PRIVATE ${OpenCV_LIBS})find_package背后有兩種查找路徑理解它們能節(jié)省大量排查時(shí)間。第一種叫 Module 模式。它是利用 cmake 內(nèi)置的FindXXX.cmake模塊在某幾個(gè)預(yù)定義路徑里去找?guī)?。大多?shù)系統(tǒng)庫都走這種模式比如find_package(Threads)、find_package(CURL)。這種模式里cmake 會設(shè)置一些約定變量比如常見的XXX_FOUND、XXX_INCLUDE_DIRS、XXX_LIBRARIES。第二種叫 Config 模式。庫在安裝時(shí)會攜帶一個(gè)XXXConfig.cmake或xxx-config.cmake配置文件里面對這個(gè)庫的目標(biāo)、版本、依賴關(guān)系做了聲明。cmake 通過搜索CMAKE_PREFIX_PATH、系統(tǒng)默認(rèn)安裝路徑等地方來找到這個(gè)配置文件?，F(xiàn)代庫越來越傾向于走 Config 模式因?yàn)樾畔⑼暾铱梢灾苯颖┞督otarget_link_libraries使用。如果庫始終找不到第一步不是改路徑而是確認(rèn)你裝的庫版本里真的有沒有對應(yīng)的 CMake 配置文件。有時(shí)候你從 apt 安裝了一個(gè)庫但只裝了運(yùn)行時(shí)和頭文件沒裝-dev包配置文件自然就沒有。裝 Linux 下的庫務(wù)必把名稱帶dev的那個(gè)包一起裝上。find_package的REQUIRED關(guān)鍵字強(qiáng)烈建議寫上。少了它找不到庫時(shí) cmake 只會靜默地跳過后續(xù)用到這個(gè)庫的代碼會在編譯階段報(bào)出一堆看不懂的錯誤排查難度成倍增加。寫上REQUIREDcmake 會在配置階段直接報(bào)錯并告訴你到底是哪個(gè)包沒找到省心得多。4.3 安裝與導(dǎo)出讓庫可以被別人 find_package如果你開發(fā)的是庫光能編譯出自己的目標(biāo)還不夠還得讓別人在項(xiàng)目里通過 find_package 用上。這套玩法叫安裝規(guī)則與導(dǎo)出目標(biāo)。核心就兩條命令。第一條是install(TARGETS ...)把庫和頭文件安裝到指定目錄。第二條是install(EXPORT ...)把構(gòu)建時(shí)的目標(biāo)信息導(dǎo)出到一個(gè)配置文件里。下面這個(gè)例子很典型add_library(mycore STATIC core.cpp) target_include_directories(mycore PUBLIC $BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR} $INSTALL_INTERFACE:include ) install(TARGETS mycore EXPORT MyCoreTargets ARCHIVE DESTINATION lib LIBRARY DESTINATION lib ) install(DIRECTORY include/ DESTINATION include) install(EXPORT MyCoreTargets FILE MyCoreConfig.cmake DESTINATION lib/cmake/MyCore )這里的$BUILD_INTERFACE:和$INSTALL_INTERFACE:又要用到生成器表達(dá)式了編譯階段把頭文件路徑指向源碼目錄安裝后則指向安裝目錄下的 include 路徑。這種設(shè)計(jì)我在實(shí)際維護(hù)公共庫時(shí)用得很頻繁一條規(guī)則通吃“開發(fā)時(shí)引用”和“安裝后引用”兩種場景根本不需要操心頭文件路徑對不上。5. 構(gòu)建配置、編譯器差異與并行構(gòu)建優(yōu)化5.1 構(gòu)建類型單配置與多配置生成器cmake 的構(gòu)建類型是另一個(gè)高頻困惑點(diǎn)。有人問為什么我在 VS 里能直接切 Debug/Release但命令行卻要傳-DCMAKE_BUILD_TYPERelease這其實(shí)取決于你用的是哪種生成器。Makefile 和 Ninja 屬于“單配置生成器”一次配置只能選定一個(gè)構(gòu)建類型所以必須通過CMAKE_BUILD_TYPE在配置階段指定。VS 和 Xcode 屬于“多配置生成器”一個(gè)構(gòu)建目錄內(nèi)可以同時(shí)存在 Debug、Release、RelWithDebInfo 等配置構(gòu)建時(shí)再用--config選項(xiàng)指定用哪個(gè)。如果你當(dāng)初用默認(rèn)方式在 Windows 上跑了cmake -S . -B build大概率生成的是 VS 工程。這時(shí)指令就要寫成cmake --build build --config Release我看到過不少人在 Windows 命令行下執(zhí)行cmake --build build死活出不來 Release 程序最后才發(fā)現(xiàn)默認(rèn)生成的是 Debug。所以閱讀構(gòu)建日志時(shí)一定要先確認(rèn)自己用的生成器類型然后對癥下藥。構(gòu)建類型的差異還會影響優(yōu)化級別。Release 默認(rèn)-O3Debug 默認(rèn)不帶優(yōu)化、帶調(diào)試符號除此之外某些宏定義比如NDEBUG也是隨構(gòu)建類型切換的。我自己做性能排查時(shí)經(jīng)常要在同一個(gè)功能下各自編一版 Debug 和 Release 對比行為對這種差異尤其敏感。5.2 在 Windows 下用 cmake 配合 VS棧大小怎么設(shè)置這個(gè)熱詞問的人特別多。VS 里直接改棧大小可以通過鏈接器屬性面板但如果你用 cmake 管理項(xiàng)目就得通過鏈接選項(xiàng)傳給 MSVC。否則每次從 cmake 重新生成工程手動改的屬性都會丟失。MSVC 的鏈接器參數(shù)里/STACK:reserveSize,commitSize就是用來控制?？臻g的。例如希望主線程棧開到 8MB可以這樣寫if(MSVC) target_link_options(mytarget PRIVATE /STACK:8388608) endif()注意單位是字節(jié)8388608就是 8 * 1024 * 1024也就是 8MB。實(shí)際開發(fā)中我遇到過遞歸深度較大的算法把默認(rèn) 1MB 棧打滿的情況程序在隨機(jī)位置崩潰很難復(fù)現(xiàn)。用這個(gè)選項(xiàng)一下子解決了問題。如果不針對單目標(biāo)直接在全局設(shè)也行set(CMAKE_EXE_LINKER_FLAGS ${CMAKE_EXE_LINKER_FLAGS} /STACK:8388608)但這種方式會影響所有可執(zhí)行文件不夠精細(xì)。我更推薦用target_link_options這樣語義清晰后面維護(hù)一看就知道是哪個(gè)目標(biāo)需要大棧。另外需要提醒的是這個(gè)選項(xiàng)只對 Windows/MSVC 有效Linux 下線程棧大小通常是在代碼里通過pthread_attr_setstacksize控制的或者用ulimit -s調(diào)整進(jìn)程級棧限制兩者機(jī)制不一樣不要把 Windows 這一套直接搬過去。5.3 并行構(gòu)建與增量編譯cmake 構(gòu)建的性能優(yōu)化很多時(shí)候反而是底層構(gòu)建系統(tǒng)決定的。Ninja 在并發(fā)行和增量編譯上的表現(xiàn)比傳統(tǒng) Makefile 好不少。我自己現(xiàn)在幾乎全部項(xiàng)目都用 Ninja 生成器構(gòu)建速度快、輸出干凈。指定 Ninja 的方法很簡單cmake -S . -B build -G Ninja cmake --build buildNinja 默認(rèn)會充分利用 CPU 并行度所以不需要額外傳-j。如果用 Makefile 生成器并行需要顯式指定cmake --build build -j 8這里的-j是并發(fā)任務(wù)的個(gè)數(shù)通常設(shè)為核心數(shù)或略微高一點(diǎn)比較合適。太低了浪費(fèi)時(shí)間太高了容易吃滿內(nèi)存把機(jī)器拖垮。我的經(jīng)驗(yàn)是 8 核機(jī)器用-j 8就挺好16 核機(jī)器用-j 16沒必要再往上加。增量編譯同樣是提升效率的關(guān)鍵。cmake 的構(gòu)建系統(tǒng)會自動跟蹤每個(gè)目標(biāo)的依賴文件改哪個(gè)文件就只重編哪個(gè)文件。但這里有個(gè)容易被忽略的問題如果你改了 CMakeLists.txtcmake 需要重新配置才能正確跟蹤新的依賴關(guān)系否則可能漏編譯。改完 CMakeLists.txt 后不要只跑cmake --build一定要先重新配置一次。6. 常見問題與排查技巧實(shí)錄6.1 經(jīng)典錯誤The following variables are used in this project這個(gè)報(bào)錯的全稱通常是CMake Error: The following variables are used in this project, but they are set to NOTFOUND。它看起來像天書實(shí)際含義很簡單CMakeLists.txt 里引用了某個(gè)變量但這個(gè)變量在配置階段變成了XXX_NOTFOUND。多半是find_package或者find_library沒有找到對應(yīng)的庫。最常見的觸發(fā)場景是第三方依賴缺失。比如你寫了find_package(CURL REQUIRED)但系統(tǒng)里壓根沒有裝 libcurlcmake 會在配置階段把CURL_LIBRARY設(shè)置成CURL_LIBRARY-NOTFOUND最終報(bào)出這個(gè)錯誤。排查思路按照這個(gè)順序走錯誤特征可能原因排查操作XXX_LIBRARY-NOTFOUND庫未安裝或路徑錯誤先確認(rèn)find_package(XXX)是否成功再檢查庫文件是否存在XXX_INCLUDE_DIR-NOTFOUND頭文件目錄未找到檢查頭文件是否安裝CMAKE_PREFIX_PATH是否指向正確前綴報(bào)錯出現(xiàn)在某個(gè)自定義變量CMakeLists.txt 邏輯錯誤檢查set或message的變量名拼寫是否一致還有個(gè)小技巧在 CMakeLists.txt 里臨時(shí)加一行message(STATUS XXX_LIBRARY${XXX_LIBRARY})重新配置就能直接在控制臺看到變量到底被解析成了什么。這個(gè)辦法在排查任何“我覺得我明明設(shè)置了但它還是 NOTFOUND”的場景時(shí)都非常有效。6.2 緩存殘留與“我改了都沒生效”這個(gè)問題幾乎每個(gè)用 cmake 的人都會撞上幾次?，F(xiàn)象是改了某個(gè)-D參數(shù)或者改了系統(tǒng)某個(gè)環(huán)境變量甚至已經(jīng)重新執(zhí)行了 configure但 cmake 依然使用舊的值。造成這種情況的根源是 CMakeCache.txt。cmake 在第一次配置時(shí)會把所有緩存變量記錄下來。后續(xù)重新配置時(shí)如果你沒有在命令行里明確指定某個(gè)變量cmake 會沿用緩存里已有的值而不是重新去探測。這在設(shè)計(jì)上是故意的目的是加快配置速度但也造成了很多誤判。處理辦法就一句話當(dāng)你懷疑“改了沒生效”時(shí)直接把 build 目錄刪掉重建。rm -rf build cmake -S . -B build這個(gè)操作我每周都會做上幾次尤其是從別人那里接手一個(gè)構(gòu)建目錄時(shí)。刪除緩存雖然會讓配置時(shí)間變長不少但能保證一切從干凈狀態(tài)開始排查思路會清晰很多。如果你舍不得刪整個(gè)構(gòu)建目錄也可以只刪 CMakeCache.txt。但需要注意有些生成文件是在配置階段根據(jù)舊緩存生成的單獨(dú)刪緩存偶爾會造成不一致所以還是整個(gè)目錄重建最穩(wěn)妥。6.3 交叉編譯場景下的 toolchain 文件不只是嵌入式項(xiàng)目現(xiàn)在不少人也會在 Windows 上開發(fā) Linux 的產(chǎn)物或者在 x86 的機(jī)器上編譯 ARM 的代碼。cmake 對這類場景的標(biāo)準(zhǔn)解法是編寫一個(gè) toolchain 文件然后通過-DCMAKE_TOOLCHAIN_FILE指定。一個(gè)典型的交叉編譯 toolchain 文件大概長這樣set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_PROCESSOR arm) set(CMAKE_C_COMPILER arm-linux-gnueabihf-gcc) set(CMAKE_CXX_COMPILER arm-linux-gnueabihf-g) set(CMAKE_FIND_ROOT_PATH /path/to/arm/sysroot) set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)這份文件的核心作用是告訴 cmake 三件事目標(biāo)平臺是什么、用什么編譯器、去哪里找目標(biāo)環(huán)境的頭文件和庫。CMAKE_FIND_ROOT_PATH在這里尤其重要它讓find_package去交叉編譯的 sysroot 目錄里找依賴而不是去宿主機(jī)的系統(tǒng)目錄里找。否則很容易出現(xiàn)棋差一著的錯誤比如在 x86 機(jī)器上找到了 x86 版本的 OpenSSL鏈接出來的 arm 版本程序直接運(yùn)行失敗這在嵌入式開發(fā)里是典型的配置陷阱。這類問題排查起來比較陰間最好的方法還是從第一步就正確使用 toolchain 文件并保證CMAKE_FIND_ROOT_PATH指對。6.4 常見構(gòu)建錯誤速查表報(bào)錯信息可能原因解決思路No CMAKE_CXX_COMPILER found編譯器未安裝或未在 PATH 中確認(rèn) g/clang 可用重新配置CMake Error at ... add_library cannot create target目標(biāo)名與已有庫沖突檢查項(xiàng)目內(nèi)是否重復(fù)定義同名目標(biāo)Cannot specify include directories for imported target對 IMPORTED 目標(biāo)錯誤使用了 include 指令改用 target_link_libraries 或 INTERFACE 屬性The CXX compiler identification is unknown編譯器無法識別或配置被緩存污染刪除 build 目錄后重新配置ninja: error: unknown argument語法問題或者生成器與 cmake 版本不匹配檢查構(gòu)建命令改用cmake --buildundefined reference to ...鏈接庫順序或庫未鏈接檢查 target_link_libraries確認(rèn)目標(biāo)傳播屬性正確最后再分享一個(gè)小技巧如果你要給 cmake 生成一個(gè)“干凈利落”的編譯數(shù)據(jù)庫用于編輯器或 IDE 的代碼索引可以在 CMakeLists.txt 里加一行set(CMAKE_EXPORT_COMPILE_COMMANDS ON)配置完成后構(gòu)建目錄下會生成compile_commands.json這里記錄了每個(gè)源文件用什么樣的編譯選項(xiàng)。我給 clangd 指向這個(gè)文件VSCode 或 vim 里的補(bǔ)全、跳轉(zhuǎn)和編譯選項(xiàng)就和 cmake 完全一致了。平時(shí)寫代碼時(shí)再也不用擔(dān)心“IDE 里不報(bào)錯實(shí)際編譯卻報(bào)錯”這種尷尬局面。這也是我對 cmake 最深的體會它本質(zhì)上不是一個(gè)與你日常寫代碼割裂的環(huán)節(jié)而是連接源碼和工具鏈的橋梁。多花點(diǎn)時(shí)間把構(gòu)建邏輯理順后面幾年省下的時(shí)間絕對值得。平時(shí)養(yǎng)成“讀 CMakeLists.txt 時(shí)多問一句為什么這樣寫”的習(xí)慣踩坑的次數(shù)會少很多。