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