寫在前頭我正在整理一份完整CMake教程。前陣子有朋友跟我抱怨說(shuō)代碼在自己電腦上跑得好好的換到Linux服務(wù)器上編譯直接掛掉一查頭文件路徑全寫死成本地目錄格式了。我問(wèn)他為什么不用CMake他的回答很有意思那玩意兒太復(fù)雜我寫了三年Makefile都沒(méi)弄明白。這話我聽(tīng)過(guò)不止一遍。但說(shuō)實(shí)話CMake根本不需要當(dāng)一門編程語(yǔ)言去啃。它更像一個(gè)資產(chǎn)管理工具幫你把編譯哪些文件、用什么參數(shù)、依賴什么東西、裝到哪里去這些事說(shuō)清楚剩下的事它自動(dòng)干。這篇文章我會(huì)用模擬項(xiàng)目X一個(gè)叫imgproc的小圖像處理庫(kù)從單文件到可安裝發(fā)布版的完整過(guò)程把CMake里真正常用、真正容易踩坑的知識(shí)點(diǎn)挨個(gè)過(guò)一遍。適合兩類人C/C項(xiàng)目剛起步、覺(jué)得Makefile難以維護(hù)的新手以及已經(jīng)會(huì)用CMakeLists.txt、但一直靠復(fù)制粘貼改改、不太理解背后邏輯的進(jìn)階用戶。1. 為什么是CMakeMakefile解決不了的那攤子事先聊動(dòng)機(jī)。很多人寫C/C程序最初的構(gòu)建方式就是一條gcc命令后來(lái)文件多了就上Makefile。但Makefile有個(gè)天生缺陷它描述的是一條條具體的構(gòu)建命令而這些命令依賴具體的操作系統(tǒng)、編譯器、路徑風(fēng)格。1.1 手寫構(gòu)建腳本的死穴同樣是編譯一個(gè)靜態(tài)庫(kù)Linux下ar打出來(lái)的庫(kù)叫l(wèi)ibxxx.aWindows下lib.exe打出來(lái)的叫xxx.lib同樣的頭文件搜索路徑Linux用冒號(hào)分隔Windows用分號(hào)編譯選項(xiàng)更是完全兩套GCC用-O2 -WallMSVC得用/O2 /W3。如果一份代碼要跨平臺(tái)交付你手寫Makefile就得同時(shí)維護(hù)好幾套規(guī)則再加一層if層判斷系統(tǒng)。我見(jiàn)過(guò)不少項(xiàng)目就是這么縫出來(lái)的一套Makefile里堆滿ifeq ($(OS),Windows_NT)另一套.bat批處理文件負(fù)責(zé)Windows下的構(gòu)建。每次改依賴、加目錄、調(diào)參數(shù)兩邊都要同步改稍不留神就漏一處然后就是長(zhǎng)達(dá)半天的心智損耗排查。1.2 CMake的核心思想描述目標(biāo)而不是描述命令CMake換了個(gè)思路。你的CMakeLists.txt不寫怎么編譯只寫這個(gè)項(xiàng)目有哪些目標(biāo)(target)每個(gè)目標(biāo)包含哪些源文件、需要什么頭文件路徑、鏈接什么庫(kù)。至于編譯器怎么調(diào)用、靜態(tài)庫(kù)叫什么后綴、路徑用什么分隔符CMake會(huì)在配置階段根據(jù)當(dāng)前平臺(tái)的默認(rèn)規(guī)則自己搞定。這就是它自稱為元構(gòu)建系統(tǒng)的原因CMake本身不直接編譯代碼它根據(jù)一份抽象描述生成當(dāng)前平臺(tái)最合適的構(gòu)建文件Linux下生成MakefileWindows下可以生成Visual Studio工程也可以生成Ninja文件。1.3 兩階段執(zhí)行模型先畫(huà)圖紙?jiān)偈┕だ斫釩Make的關(guān)鍵是搞清楚它的兩階段執(zhí)行模型。配置階段Configure是CMake讀取CMakeLists.txt、執(zhí)行各種邏輯、探測(cè)環(huán)境的過(guò)程最后生成一套構(gòu)建文件。構(gòu)建階段Build是你真正調(diào)用編譯器、鏈接器出產(chǎn)物的過(guò)程。這兩件事分離帶來(lái)一個(gè)好處同一個(gè)項(xiàng)目可以保持多套構(gòu)建目錄一套Debug、一套R(shí)elease、一套帶靜態(tài)分析工具互不干擾隨時(shí)切換。這也是為什么我們習(xí)慣用cmake -S . -B build單獨(dú)指定目錄讓源碼樹(shù)保持干凈。形象點(diǎn)說(shuō)CMake是畫(huà)圖紙的設(shè)計(jì)師Make/Ninja是拿著圖紙施工的隊(duì)伍。理解了這個(gè)模型后面看到變量緩存、生成器表達(dá)式這些概念就不會(huì)發(fā)怵它們都是在配置階段這一層做文章。2. 最小CMake項(xiàng)目從一行打印到雙目錄結(jié)構(gòu)好理論先放一邊直接上手。模擬項(xiàng)目X最初只有一個(gè)main.cpp功能是讀一張圖片做灰度化。最基礎(chǔ)的CMakeLists.txt長(zhǎng)這樣cmake_minimum_required(VERSION 3.16) project(imgproc) add_executable(imgproc_demo main.cpp)這就是起步所需的最小集合。cmake_minimum_required不只是檢查版本號(hào)它還設(shè)置CMake的策略級(jí)別決定哪些新版本的行為變更會(huì)生效這會(huì)影響后面很多語(yǔ)法細(xì)節(jié)。project命令有兩件事要做設(shè)置項(xiàng)目名以及探測(cè)當(dāng)前環(huán)境支持的C/C編譯器。add_executable是主角命令聲明一個(gè)可執(zhí)行目標(biāo)。目標(biāo)是CMake里的頭等公民后續(xù)的include路徑、編譯選項(xiàng)、鏈接庫(kù)全部圍繞目標(biāo)展開(kāi)。2.1 構(gòu)建流程為什么強(qiáng)烈建議用 -B 參數(shù)配置和構(gòu)建的命令長(zhǎng)這樣cmake -S . -B build cmake --build build-S .指定源碼目錄-B build指定構(gòu)建目錄。這里我多說(shuō)一句很多舊教程教你mkdir build cd build cmake ..效果差不多但-S -B寫法更直白尤其當(dāng)源碼目錄和構(gòu)建目錄不在相鄰位置時(shí)一眼就能看懂誰(shuí)是誰(shuí)。構(gòu)建產(chǎn)物全部落在build里源碼目錄只有一份干凈的CMakeLists.txt和源碼就算你同時(shí)開(kāi)一個(gè)build-debug和一個(gè)build-release也不會(huì)互相污染。2.2 遇到的第一批問(wèn)題頭文件路徑與源文件膨脹很快main.cpp就膨脹了我把圖像格式解析拆到img_format.cpp把濾波算法拆到filter.cpp。這時(shí)候CMakeLists變成cmake_minimum_required(VERSION 3.16) project(imgproc) add_executable(imgproc_demo main.cpp img_format.cpp filter.cpp ) target_include_directories(imgproc_demo PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)target_include_directories這條命令值得重點(diǎn)講。它把某個(gè)頭文件搜索路徑作用到指定目標(biāo)上PRIVATE表示這個(gè)路徑只對(duì)imgproc_demo自己有效。后續(xù)如果別的目標(biāo)也要用這些頭文件得單獨(dú)聲明。2.3 拆庫(kù)add_library、target_link_libraries與依賴傳遞代碼量繼續(xù)上漲main.cpp引用的函數(shù)越來(lái)越多編譯單元之間的依賴也亂了。這時(shí)候一個(gè)想法很自然把圖像格式解析和濾波算法拆成一個(gè)獨(dú)立的庫(kù)讓main.cpp只做入口邏輯順便以后寫單元測(cè)試時(shí)不用重復(fù)編譯全部源碼。于是拆成一層靜態(tài)庫(kù)cmake_minimum_required(VERSION 3.16) project(imgproc) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) add_library(imgproc_core STATIC img_format.cpp filter.cpp ) add_executable(imgproc_demo main.cpp) target_include_directories(imgproc_core PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/src) target_link_libraries(imgproc_demo PRIVATE imgproc_core)這里庫(kù)的類型有三種寫法STATIC靜態(tài)庫(kù)SHARED動(dòng)態(tài)庫(kù)INTERFACE頭文件庫(kù)。有接口(INTERFACE)的庫(kù)下面鏈接時(shí)會(huì)用到。target_link_libraries(imgproc_demo PRIVATE imgproc_core)既有字面意思也有隱含的傳遞邏輯。這個(gè)傳遞邏輯是多數(shù)初學(xué)者最容易懵的地方。我給個(gè)生活化解釋你家的書(shū)房imgproc_core里有一些頭文件對(duì)外暴露的接口你兒子imgproc_demo要借用書(shū)房的資料你得告訴兒子這些接口在哪兒。問(wèn)題是兒子以后要不要把書(shū)房的位置轉(zhuǎn)告給他的朋友另一個(gè)目標(biāo)PUBLIC表示我用了而且我的使用方式導(dǎo)致我的依賴方也得知道這些頭文件路徑PRIVATE表示我只是內(nèi)部實(shí)現(xiàn)用了外部不需要知道。翻譯到代碼里就是PUBLIC會(huì)把自己的include目錄、編譯定義、鏈接庫(kù)一并傳給下游目標(biāo)PRIVATE只留在當(dāng)前目標(biāo)自己這層。3. 變量、選項(xiàng)與生成器表達(dá)式配置階段的分支邏輯當(dāng)項(xiàng)目規(guī)模再上來(lái)你會(huì)發(fā)現(xiàn)CMakeLists.txt開(kāi)始寫成程序的樣子要定義變量、要根據(jù)條件走不同分支、要根據(jù)不同構(gòu)建類型施加不同參數(shù)。這一章我們把CMake的編程能力說(shuō)透。3.1 set變量與緩存變量set(VAR value)定義的是普通變量只在當(dāng)前CMakeLists.txt及其子目錄生效。還有一種緩存變量通過(guò)set(VAR value CACHE STRING 說(shuō)明)或option()定義它會(huì)被寫進(jìn)構(gòu)建目錄下的CMakeCache.txt下次配置時(shí)依然保留也可以在cmake -D命令行里覆蓋它的默認(rèn)值。舉個(gè)實(shí)際例子我給模擬項(xiàng)目X加一個(gè)開(kāi)關(guān)是否編譯測(cè)試代碼。這個(gè)開(kāi)關(guān)不能是普通變量得讓用戶構(gòu)建時(shí)能改、能覆蓋。option(BUILD_TESTING Build unit tests OFF) if(BUILD_TESTING) enable_testing() add_subdirectory(tests) endif()用option而不是set的好處是CMake緩存里會(huì)自動(dòng)生成一個(gè)可勾選的開(kāi)關(guān)圖形界面和命令行都方便調(diào)整而且默認(rèn)值只在第一次配置時(shí)生效用戶之后通過(guò)-DBUILD_TESTINGON改過(guò)會(huì)一直記住新值。3.2 if判斷里的門道if()判斷語(yǔ)句看起來(lái)和所有語(yǔ)言一樣但有幾個(gè)坑。比如if(BUILD_TESTING) # 變量為ON/OFF/TRUE/FALSE時(shí)都能解析 if(DEFINED SOME_VAR) # 判斷變量是否已定義實(shí)際工作中我建議用帶上引號(hào)的寫法避免變量值未定義時(shí)報(bào)錯(cuò)或者被當(dāng)作路徑解析if(${BUILD_TESTING})3.3 生成器表達(dá)式配置階段最后的靈活手段這是CMake里最抽象的概念也最值錢。普通變量在配置階段就被固定成字符串了而生成器表達(dá)式(Generator Expressions)可以推遲到構(gòu)建階段才求值所以它能拿到每個(gè)具體構(gòu)建目標(biāo)、具體配置類型的信息。最常用的幾個(gè)生成器表達(dá)式表達(dá)式含義$TARGET_EXISTS:name目標(biāo)是否存在$TARGET_NAME_IF_EXISTS:name目標(biāo)存在則用目標(biāo)名否則返回空$CONFIG當(dāng)前構(gòu)建配置Debug/Release等$BOOL:...把值轉(zhuǎn)成ON/OFF$BUILD_INTERFACE:...僅在使用構(gòu)建目錄時(shí)生效$INSTALL_INTERFACE:...僅在安裝后被外部項(xiàng)目使用時(shí)生效我給個(gè)具體用法。模擬項(xiàng)目X要支持一個(gè)可選特性圖像去霧。這個(gè)功能依賴OpenCV但不是每個(gè)人都有OpenCV環(huán)境于是按需編譯find_package(OpenCV QUIET) if(OpenCV_FOUND) target_sources(imgproc_core PRIVATE dehaze.cpp) target_compile_definitions(imgproc_core PRIVATE WITH_DEHAZE1) target_link_libraries(imgproc_core PRIVATE ${OpenCV_LIBS}) endif()還有更常見(jiàn)的場(chǎng)景是編譯選項(xiàng)按配置區(qū)別target_compile_options(imgproc_core PRIVATE $$CONFIG:Debug:-g3;-O0 $$CONFIG:Release:-O2;-DNDEBUG )因?yàn)閠arget_compile_options本身就允許帶生成器表達(dá)式所以Debug和Release可以一口氣寫好不用if套if。這種寫法在Makefile時(shí)代要維護(hù)兩三套規(guī)則在CMake里就一行。3.4 為什么優(yōu)先使用target_*系列命令看多了各種代碼你會(huì)發(fā)現(xiàn)CMake有兩條命令路線目錄級(jí)命令如include_directories、add_compile_options以及目標(biāo)級(jí)命令如target_include_directories、target_compile_options。我強(qiáng)烈建議新項(xiàng)目一律用target_系列。原因很簡(jiǎn)單作用域。目錄級(jí)命令一旦執(zhí)行影響的是整個(gè)目錄及其子目錄的所有目標(biāo)后面對(duì)某個(gè)目標(biāo)單獨(dú)調(diào)整時(shí)很難精準(zhǔn)覆蓋。目標(biāo)級(jí)命令則精確控制到單個(gè)目標(biāo)依賴傳遞關(guān)系也清晰。小項(xiàng)目感覺(jué)不明顯一旦目標(biāo)一多全局影響就是排查問(wèn)題的黑洞。4. 第三方依賴find_package與FetchContent的分工C/C項(xiàng)目很少是不依賴任何第三方庫(kù)的。模擬項(xiàng)目X開(kāi)始需要一個(gè)JSON解析庫(kù)需要接SQLite。這一章講依賴管理的兩種主要手段。4.1 find_package尋找系統(tǒng)里已經(jīng)裝好的庫(kù)find_package有很多人無(wú)腦用但理解它分兩種模式很有必要。Module模式CMake自帶的FindXXX.cmake模塊負(fù)責(zé)在系統(tǒng)里找?guī)煺业胶笤O(shè)置XXX_FOUND、XXX_INCLUDE_DIRS、XXX_LIBRARIES變量。Config模式庫(kù)本身安裝時(shí)提供了xxx-config.cmake文件里面定義好了導(dǎo)入目標(biāo)imported targetfind_package執(zhí)行后你可以直接用target_link_libraries(app PRIVATE xxx::xxx)這種帶命名空間的方法鏈接。后者是現(xiàn)在的趨勢(shì)因?yàn)閷?dǎo)入目標(biāo)把頭文件路徑、鏈接庫(kù)、編譯選項(xiàng)、甚至依賴的其他庫(kù)都打包好了使用方不需要自己拼路徑。find_package(spdlog CONFIG REQUIRED) target_link_libraries(imgproc_core PRIVATE spdlog::spdlog)技巧怎么查一個(gè)庫(kù)是否提供Config模式去系統(tǒng)或安裝目錄看通常會(huì)有l(wèi)ib/cmake/xxx/xxxConfig.cmake或類似路徑。如果沒(méi)有就得退到Module模式或者用下面說(shuō)的FetchContent。4.2 FetchContent構(gòu)建時(shí)直接拉源碼如果你需要的是某個(gè)特定版本的庫(kù)而且希望整個(gè)項(xiàng)目可復(fù)現(xiàn)、不依賴系統(tǒng)環(huán)境FetchContent是更省心的方案。它會(huì)在配置階段把源碼下載到構(gòu)建目錄里然后通過(guò)add_subdirectory把庫(kù)的目標(biāo)直接加進(jìn)當(dāng)前構(gòu)建。include(FetchContent) FetchContent_Declare( fmt GIT_REPOSITORY https://example.com/fmt/archive.tar.gz GIT_TAG v9.1.0 URL_HASH SHA256按實(shí)際填寫 ) FetchContent_MakeAvailable(fmt)這句話執(zhí)行完fmt庫(kù)的目標(biāo)會(huì)自動(dòng)加入直接用target_link_libraries(imgproc_core PRIVATE fmt::fmt)鏈接即可。我在實(shí)際使用中一般指定下載源碼包或Git tag并鎖定hash避免某些鏡像不穩(wěn)定或上游倉(cāng)庫(kù)變動(dòng)導(dǎo)致構(gòu)建突然失敗。4.3 兩種方式的選擇思路場(chǎng)景選哪個(gè)系統(tǒng)管理員已裝好特定版本庫(kù)希望直接用find_package項(xiàng)目要完全可復(fù)現(xiàn)不依賴他人環(huán)境FetchContent依賴庫(kù)較大編譯一次耗時(shí)較長(zhǎng)優(yōu)先f(wàn)ind_package減少無(wú)謂編譯依賴庫(kù)較小、單個(gè)頭文件為主FetchContent更簡(jiǎn)單我的習(xí)慣是外部依賴盡量?jī)?yōu)先f(wàn)ind_package當(dāng)某個(gè)庫(kù)在常見(jiàn)環(huán)境里都沒(méi)裝、或者版本不滿足要求時(shí)再退回FetchContent。兩個(gè)方案可以共存用find_package探測(cè)探測(cè)不到就用FetchContent兜底。5. 構(gòu)建類型與編譯選項(xiàng)Debug/Release的完整控制默認(rèn)情況下CMake生成的構(gòu)建系統(tǒng)可能是單配置的也可能是多配置的。這個(gè)差異直接決定你怎么指定構(gòu)建類型很多人在這里踩坑。5.1 單配置生成器與多配置生成器Unix下的Makefile是單配置的。你執(zhí)行cmake -B build -DCMAKE_BUILD_TYPEDebug配置階段就決定好了Debug之后cmake --build build編譯出來(lái)就是帶調(diào)試信息的版本。想變Release得重新開(kāi)一個(gè)構(gòu)建目錄或者改配置再重新生成。Visual Studio和Xcode是多配置的CMake生成時(shí)就同時(shí)包含Debug、Release、RelWithDebInfo等多個(gè)配置。你不需要在配置階段指定而是在構(gòu)建階段用--config選cmake --build build --config Release生成器表達(dá)式$CONFIG在多配置生成器下才有意義因?yàn)樗苣玫矫總€(gè)具體的構(gòu)建配置。如果你在單配置生成器下使用它會(huì)在配置階段就展開(kāi)成CMAKE_BUILD_TYPE的值。5.2 Debug和Release到底差在哪很多新手會(huì)問(wèn)Debug和Release的區(qū)別是CMake自己搞定的嗎答案是CMake只會(huì)挑選合適的默認(rèn)編譯選項(xiàng)但如果你有特定的優(yōu)化需求得自己加。以GCC為例CMake默認(rèn)的Debug會(huì)帶-gRelease帶-O3 -DNDEBUG。-DNDEBUG這個(gè)宏會(huì)把a(bǔ)ssert()全部禁用掉這是Release更快的原因之一也是很多依賴斷言檢查的程序在Release下看起來(lái)正常但行為變了的根源。在MSVC下Debug默認(rèn)關(guān)閉優(yōu)化并開(kāi)啟調(diào)試符號(hào)Release默認(rèn)/O2。兩者的CRT版本還不同Debug對(duì)應(yīng)多線程調(diào)試DLLRelease對(duì)應(yīng)多線程DLL混用會(huì)直接鏈接報(bào)錯(cuò)。5.3 編譯選項(xiàng)的精準(zhǔn)投放基于上面的分析我一般會(huì)在項(xiàng)目里這樣配置target_compile_options(imgproc_core PRIVATE $$CONFIG:Debug:-fno-omit-frame-pointer;-fsanitizeaddress $$CONFIG:Release:-O3;-marchnative ) target_link_options(imgproc_core PRIVATE $$CONFIG:Debug:-fsanitizeaddress )調(diào)試時(shí)開(kāi)AddressSanitizer幫助抓內(nèi)存問(wèn)題發(fā)布時(shí)開(kāi)激進(jìn)優(yōu)化。target_link_options也要跟著加因?yàn)橄駍anitize這種選項(xiàng)必須同時(shí)影響編譯階段和鏈接階段。這里有個(gè)容易被忽略的細(xì)節(jié)如果你給某個(gè)目標(biāo)開(kāi)啟了-marchnative那這個(gè)庫(kù)編譯出的二進(jìn)制就只能在本機(jī)或相同指令集的機(jī)器上跑。分發(fā)到別的機(jī)器前要重新評(píng)估。真實(shí)項(xiàng)目里我傾向于不加-marchnative改用-O2兼顧通用與性能。6. 安裝與導(dǎo)出讓構(gòu)建產(chǎn)物能被別人一鍵使用構(gòu)建好的庫(kù)如果不安裝就只能在自己構(gòu)建樹(shù)里用。想讓其他項(xiàng)目通過(guò)find_package(imgproc)的方式使用需要給模擬項(xiàng)目X補(bǔ)上安裝規(guī)則和包配置文件。6.1 install命令的常規(guī)姿勢(shì)include(GNUInstallDirs) install(TARGETS imgproc_core EXPORT imgprocTargets LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/imgproc )GNUInstallDirs會(huì)按GNU的約定幫我們把目錄設(shè)好lib放庫(kù)include放頭文件bin放可執(zhí)行文件。這樣安裝出來(lái)的布局符合大多數(shù)系統(tǒng)的慣例后面接包管理工具也方便。PUBLIC_HEADER DESTINATION是安裝公開(kāi)頭文件的一種簡(jiǎn)寫前提是你在add_library或target_sources里把這些頭文件列出來(lái)了。如果頭文件較多、目錄結(jié)構(gòu)較復(fù)雜也可以用install(DIRECTORY src/ DESTINATION include/imgproc FILES_MATCHING PATTERN *.h)打包安裝。6.2 導(dǎo)出包配置文件光安裝庫(kù)和頭文件還不夠還需要告訴別的項(xiàng)目我提供了什么目標(biāo)、依賴什么庫(kù)、版本是多少。這一塊CMake提供了輔助模塊include(CMakePackageConfigHelpers) install(EXPORT imgprocTargets FILE imgprocTargets.cmake NAMESPACE imgproc:: DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/imgproc ) configure_package_config_file( cmake/imgprocConfig.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/imgprocConfig.cmake INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/imgproc ) write_basic_package_version_file( ${CMAKE_CURRENT_BINARY_DIR}/imgprocConfigVersion.cmake VERSION ${PROJECT_VERSION} COMPATIBILITY SameMajorVersion ) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/imgprocConfig.cmake ${CMAKE_CURRENT_BINARY_DIR}/imgprocConfigVersion.cmake DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/imgproc )對(duì)應(yīng)的imgprocConfig.cmake.in模板通常長(zhǎng)這樣PACKAGE_INIT include(${CMAKE_CURRENT_LIST_DIR}/imgprocTargets.cmake)PACKAGE_INIT是configure_package_config_file處理的一段占位符它提供一些宏幫你在安裝目錄和構(gòu)建目錄之間做路徑切換。完成后其他項(xiàng)目只需find_package(imgproc CONFIG REQUIRED) target_link_libraries(my_app PRIVATE imgproc::imgproc_core)imgproc::imgproc_core的命名來(lái)自包名NAMESPACE目標(biāo)名這是CMake社區(qū)現(xiàn)在推薦的風(fēng)格能有效避免不同庫(kù)之間的目標(biāo)重名沖突。6.3 構(gòu)建樹(shù)導(dǎo)出與安裝導(dǎo)出的區(qū)別export(EXPORT ...)和install(EXPORT ...)都能導(dǎo)出目標(biāo)但用處完全不同。export導(dǎo)出的是當(dāng)前構(gòu)建樹(shù)里的目標(biāo)只在這臺(tái)機(jī)器上、這個(gè)構(gòu)建目錄里有效主要用于同一個(gè)工程內(nèi)的子項(xiàng)目互連。install(EXPORT)則生成安裝樹(shù)里的配置文件跟著庫(kù)一起部署到系統(tǒng)里這是面向其他項(xiàng)目的接口。實(shí)際交付外部庫(kù)時(shí)我?guī)缀踔挥胕nstall導(dǎo)出。如果只是內(nèi)部多個(gè)可執(zhí)行文件共享代碼是不需要走安裝這一步的直接add_subdirectory加target_link_libraries就夠了。7. 避坑清單這些年踩過(guò)的CMake坑CMake語(yǔ)法不難坑都在細(xì)節(jié)里。這一章集中記錄我在實(shí)際項(xiàng)目里反復(fù)踩過(guò)的幾類問(wèn)題很多是從同事和社區(qū)里學(xué)來(lái)的教訓(xùn)。7.1 不要用CMAKE_SOURCE_DIR判斷當(dāng)前項(xiàng)目路徑CMAKE_SOURCE_DIR指向最頂層源碼目錄PROJECT_SOURCE_DIR指向最近一次調(diào)用project()的目錄。如果你的主項(xiàng)目通過(guò)add_subdirectory引入了一大堆別的項(xiàng)目這些宏的取值會(huì)不一樣。# 在子項(xiàng)目里用 ${CMAKE_SOURCE_DIR} 時(shí)指向的是主項(xiàng)目根目錄不是當(dāng)前子項(xiàng)目 target_include_directories(imgproc_core PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)正確姿勢(shì)是${CMAKE_CURRENT_SOURCE_DIR}它永遠(yuǎn)表示當(dāng)前CMakeLists.txt所在的目錄。每當(dāng)我看到${CMAKE_SOURCE_DIR}/src這種寫法第一反應(yīng)就是查這個(gè)變量用在了哪個(gè)CMakeLists里。7.2 file(GLOB)收集源文件的隱患file(GLOB sources src/*.cpp)會(huì)自動(dòng)收集目錄下的源文件用起來(lái)很爽但有個(gè)隱蔽問(wèn)題CMake不會(huì)自動(dòng)追蹤新加入的文件。你往目錄里加一個(gè)cpp如果配置階段沒(méi)重新跑構(gòu)建系統(tǒng)就不會(huì)把它編進(jìn)去。新版本可以用file(GLOB sources CONFIGURE_DEPENDS src/*.cpp)讓CMake在每次構(gòu)建前重新檢查文件變化代價(jià)是一些構(gòu)建系統(tǒng)的額外開(kāi)銷。但我仍然建議大項(xiàng)目手動(dòng)列出源文件或者至少把這種寫法局限在非常穩(wěn)定的目錄里。手動(dòng)列出來(lái)的另一個(gè)好處是代碼審查時(shí)能直觀看到新增了哪些編譯單元。7.3 CMakeCache.txt請(qǐng)不要手工改配置階段生成的所有緩存變量都存在CMakeCache.txt里。有些同學(xué)排查問(wèn)題時(shí)喜歡直接編輯這個(gè)文件改完當(dāng)時(shí)有效下次配置又被覆蓋而且格式稍有差池整個(gè)配置就壞了。我的建議是改緩存值一律用命令行cmake -S . -B build -DCMAKE_BUILD_TYPERelease如果你發(fā)現(xiàn)改了之后沒(méi)生效先把build目錄刪掉重新配置。構(gòu)建系統(tǒng)損壞時(shí)的經(jīng)典操作就是刪掉構(gòu)建目錄再重新來(lái)這比任何修復(fù)都干凈。7.4 add_subdirectory與FetchContent的二進(jìn)制沖突當(dāng)一個(gè)庫(kù)既可能被add_subdirectory引入又可能被FetchContent引入或者同一個(gè)庫(kù)在項(xiàng)目的不同層級(jí)被多次加入時(shí)會(huì)碰到目標(biāo)重名最常見(jiàn)的報(bào)錯(cuò)是add_library cannot create target ... because another target with the same name already exists。解決辦法是先用find_package探測(cè)探測(cè)不到再用FetchContent或者給子項(xiàng)目加上統(tǒng)一的前綴路徑。這里有個(gè)很實(shí)用的習(xí)慣在fetch新依賴時(shí)指定EXCLUDE_FROM_ALL避免它的所有目標(biāo)都默認(rèn)參與全量編譯否則構(gòu)建時(shí)間會(huì)失控。7.5 跨平臺(tái)編譯選項(xiàng)的寫法差異給GCC寫的編譯選項(xiàng)MSVC不認(rèn)識(shí)反之亦然。所以跨平臺(tái)項(xiàng)目里的編譯選項(xiàng)要分平臺(tái)給比較穩(wěn)的寫法是if(MSVC) target_compile_options(imgproc_core PRIVATE /W4 /permissive-) else() target_compile_options(imgproc_core PRIVATE -Wall -Wextra -Wpedantic) endif()MSVC變量只在Windows MSVC編譯器時(shí)定義用它可以干凈地把兩套參數(shù)分開(kāi)。如果你不知道某個(gè)選項(xiàng)是否兼容最穩(wěn)妥的辦法是看庫(kù)的開(kāi)源項(xiàng)目怎么處理或者用check_cxx_compiler_flag先做編譯器能力探測(cè)。7.6 C標(biāo)準(zhǔn)設(shè)置引用全局變量不如目標(biāo)級(jí)設(shè)置set(CMAKE_CXX_STANDARD 17)是全局設(shè)置對(duì)之后創(chuàng)建的所有目標(biāo)生效但也容易影響通過(guò)add_subdirectory引入的其他子項(xiàng)目。推薦做法是把標(biāo)準(zhǔn)設(shè)在目標(biāo)級(jí)別target_compile_features(imgproc_core PUBLIC cxx_std_17)cxx_std_17是CMake內(nèi)置的特性名設(shè)置后如果編譯器不支持C17配置階段就直接報(bào)錯(cuò)不會(huì)等到編譯到某個(gè)語(yǔ)法時(shí)才發(fā)現(xiàn)。7.7 調(diào)試CMake腳本最實(shí)用的工具最后分享一個(gè)實(shí)戰(zhàn)技巧message()是調(diào)試CMake時(shí)的首選武器。message(STATUS imgproc_core include dirs: ${CMAKE_CURRENT_SOURCE_DIR}/src) message(WARNING This branch is deprecated, consider refactoring) message(FATAL_ERROR Stop now, this config is invalid)FATAL_ERROR會(huì)在配置階段直接掐斷輸出紅色信息非常適合用來(lái)做前置條件校驗(yàn)。我經(jīng)常在大型項(xiàng)目的配置邏輯里加一段if(NOT DEFINED REQUIRED_FEATURE_X) message(FATAL_ERROR Required feature X is missing, set -DREQUIRED_FEATURE_XON) endif()另外cmake --build build --verbose可以打印出實(shí)際執(zhí)行的編譯命令排查為什么參數(shù)沒(méi)生效時(shí)很有用。如果想追某條變量是怎么來(lái)的cmake --trace系列能打印配置階段每一行的執(zhí)行痕跡能把你從變量謎題里救出來(lái)。寫在最后我在實(shí)際用CMake幫模擬項(xiàng)目X完成所有這些重構(gòu)之后最大的感受是CMake真正的主戰(zhàn)場(chǎng)不是語(yǔ)法集錦而是構(gòu)建系統(tǒng)的維護(hù)成本。把target抽象用好、把傳遞依賴?yán)砬濉雅渲秒A段和構(gòu)建階段分清楚大部分項(xiàng)目場(chǎng)景都能應(yīng)對(duì)。最后再分享一個(gè)小建議不要沉迷于把CMakeLists.txt寫成萬(wàn)能模板。很多項(xiàng)目需要的東西就是那么幾條命令保持簡(jiǎn)單直接讓人能看懂比炫技重要得多。等真有需求了再去查文檔按需加查一次用一次慢慢就會(huì)形成你自己的套路。