1. 從一個(gè)讓人抓狂的編譯報(bào)錯(cuò)說(shuō)起如果你寫(xiě)過(guò)C尤其是用Qt寫(xiě)桌面端項(xiàng)目大概率遇到過(guò)這種場(chǎng)景代碼在IDE里看著一切正常頭文件路徑有高亮函數(shù)跳轉(zhuǎn)也能用但一按編譯按鈕滿(mǎn)屏的紅色錯(cuò)誤就撲面而來(lái)——fatal error: xxx.h: No such file or directory或者鏈接階段突然告訴你undefined reference to xxx。你明明記得這個(gè)庫(kù)昨天還能用今天換了個(gè)目錄結(jié)構(gòu)就全崩了。這就是Qt設(shè)置引用路徑問(wèn)題的典型表現(xiàn)。它不是什么高深的技術(shù)難題但絕對(duì)是消耗開(kāi)發(fā)者耐心最多的“日?？印敝?。我見(jiàn)過(guò)不少工作兩三年的開(kāi)發(fā)者每次遇到路徑問(wèn)題還是靠“瞎試”——加個(gè)INCLUDEPATH不行就加LIBSLIBS不行就改.pro文件順序最后碰巧編譯過(guò)了但問(wèn)他為什么能過(guò)他說(shuō)不上來(lái)。這篇文章想解決的問(wèn)題很具體把Qt項(xiàng)目中引用路徑的配置邏輯徹底講清楚。包括頭文件路徑、庫(kù)文件路徑、運(yùn)行時(shí)路徑這三類(lèi)核心路徑分別在什么階段起作用qmake和CMake兩套構(gòu)建系統(tǒng)下怎么配置以及跨平臺(tái)Windows、Linux、macOS時(shí)路徑寫(xiě)法有什么差異。適合所有正在用Qt做項(xiàng)目、被路徑問(wèn)題折磨過(guò)、或者想提前避坑的開(kāi)發(fā)者。不管你是剛接觸Qt的新手還是用了幾年但一直沒(méi)系統(tǒng)梳理過(guò)路徑配置的老手下面這些內(nèi)容應(yīng)該都能幫你省下不少查資料和試錯(cuò)的時(shí)間。2. 為什么路徑配置這么容易出問(wèn)題2.1 編譯期、鏈接期、運(yùn)行期的路徑是三件不同的事很多人把“引用路徑”當(dāng)成一個(gè)籠統(tǒng)的概念這是所有混亂的根源。實(shí)際上一個(gè)Qt項(xiàng)目從源碼到可執(zhí)行程序路徑在三個(gè)完全不同的階段發(fā)揮作用每個(gè)階段由不同的工具處理配置方式也完全不同。編譯期處理的是頭文件路徑。編譯器需要找到#include指令引用的.h或.hpp文件。這個(gè)階段由INCLUDEPATHqmake或target_include_directoriesCMake控制。如果這里配錯(cuò)了報(bào)錯(cuò)就是fatal error: xxx.h: No such file or directory。鏈接期處理的是庫(kù)文件路徑。鏈接器需要找到.lib、.a、.so、.dylib這些二進(jìn)制庫(kù)文件把符號(hào)引用解析成實(shí)際地址。這個(gè)階段由LIBSqmake或target_link_librariesCMake控制。配錯(cuò)了就是undefined reference或cannot find -lxxx。運(yùn)行期處理的是動(dòng)態(tài)庫(kù)加載路徑。程序啟動(dòng)時(shí)操作系統(tǒng)需要找到它依賴(lài)的動(dòng)態(tài)庫(kù)。Windows下是.dllLinux下是.somacOS下是.dylib。這個(gè)階段跟構(gòu)建系統(tǒng)沒(méi)關(guān)系了取決于系統(tǒng)的庫(kù)搜索機(jī)制。配錯(cuò)了就是程序啟動(dòng)時(shí)報(bào)“找不到xxx.dll”或者“error while loading shared libraries”。我剛開(kāi)始用Qt的時(shí)候最常犯的錯(cuò)誤就是把這三個(gè)階段混在一起。比如編譯通過(guò)了、鏈接也通過(guò)了但一運(yùn)行就崩潰然后回頭去改INCLUDEPATH完全改錯(cuò)了方向。后來(lái)我才養(yǎng)成習(xí)慣看到報(bào)錯(cuò)先判斷是哪個(gè)階段的問(wèn)題再去改對(duì)應(yīng)的配置。這個(gè)判斷習(xí)慣至少幫我節(jié)省了一半的排查時(shí)間。2.2 qmake和CMake的路徑處理邏輯差異Qt早期項(xiàng)目幾乎都用qmake.pro文件是標(biāo)配?，F(xiàn)在新項(xiàng)目越來(lái)越多用CMakeQt官方從Qt6開(kāi)始也主推CMake。兩套系統(tǒng)處理路徑的邏輯有本質(zhì)區(qū)別不能混著理解。qmake的路徑處理相對(duì)“扁平”。你在.pro文件里寫(xiě)的INCLUDEPATH ./includeqmake會(huì)把它轉(zhuǎn)換成編譯命令的-I參數(shù)。相對(duì)路徑的基準(zhǔn)是.pro文件所在的目錄。LIBS -L./lib -lmylib同理-L指定庫(kù)搜索目錄-l指定庫(kù)名。qmake不太區(qū)分“構(gòu)建目錄”和“源碼目錄”相對(duì)路徑的解析規(guī)則比較直觀(guān)但也容易在影子構(gòu)建shadow build時(shí)出問(wèn)題。CMake的路徑處理更“結(jié)構(gòu)化”。它區(qū)分CMAKE_SOURCE_DIR、CMAKE_BINARY_DIR、CMAKE_CURRENT_SOURCE_DIR等多個(gè)路徑變量還有target_include_directories的PUBLIC、PRIVATE、INTERFACE作用域區(qū)分。好處是大型項(xiàng)目管理更清晰壞處是學(xué)習(xí)曲線(xiàn)陡。很多人從qmake轉(zhuǎn)到CMake時(shí)最不適應(yīng)的就是“為什么我寫(xiě)的相對(duì)路徑找不到文件”——因?yàn)镃Make的相對(duì)路徑基準(zhǔn)可能不是你以為的那個(gè)目錄。提示如果你在CMake項(xiàng)目里用相對(duì)路徑永遠(yuǎn)用${CMAKE_CURRENT_SOURCE_DIR}或${CMAKE_CURRENT_BINARY_DIR}做前綴不要直接寫(xiě)./xxx。這是我從無(wú)數(shù)次“本地能編譯、CI上掛掉”的教訓(xùn)里總結(jié)出來(lái)的。2.3 跨平臺(tái)帶來(lái)的路徑分隔符和搜索規(guī)則差異Windows用反斜杠\做路徑分隔符Linux和macOS用正斜杠/。雖然Qt和大多數(shù)構(gòu)建工具在內(nèi)部會(huì)做轉(zhuǎn)換但你在.pro或CMakeLists.txt里寫(xiě)路徑時(shí)最好統(tǒng)一用正斜杠/。qmake和CMake都能正確識(shí)別正斜杠但反斜杠在CMake里是轉(zhuǎn)義字符容易出幺蛾子。更麻煩的是動(dòng)態(tài)庫(kù)的搜索規(guī)則。Windows下可執(zhí)行文件會(huì)先在當(dāng)前目錄找.dll然后按PATH環(huán)境變量找。Linux下LD_LIBRARY_PATH環(huán)境變量和/etc/ld.so.conf配置決定搜索路徑當(dāng)前目錄默認(rèn)不在搜索范圍內(nèi)。macOS用DYLD_LIBRARY_PATH和rpath機(jī)制。這些差異導(dǎo)致同一個(gè)項(xiàng)目在不同平臺(tái)上可能需要不同的運(yùn)行時(shí)路徑配置。我做過(guò)一個(gè)跨三平臺(tái)的項(xiàng)目最頭疼的就是macOS的rpath。Windows和Linux下配好LIBS就能跑macOS下編譯鏈接都沒(méi)問(wèn)題一運(yùn)行就報(bào)dyld: Library not loaded。后來(lái)才搞明白需要在鏈接時(shí)加-rpath參數(shù)把庫(kù)的運(yùn)行時(shí)搜索路徑寫(xiě)進(jìn)可執(zhí)行文件。這個(gè)坑我踩了整整一個(gè)下午查了無(wú)數(shù)資料才搞定。3. qmake下的路徑配置實(shí)操3.1 INCLUDEPATH的正確寫(xiě)法與常見(jiàn)誤區(qū)INCLUDEPATH是qmake里最常用的路徑變量控制編譯器的頭文件搜索路徑。基本寫(xiě)法很簡(jiǎn)單INCLUDEPATH ./include INCLUDEPATH ../thirdparty/libxml2/include INCLUDEPATH /usr/local/include/opencv4但這里有幾個(gè)容易踩的坑。第一個(gè)坑是相對(duì)路徑的基準(zhǔn)問(wèn)題。qmake解析INCLUDEPATH里的相對(duì)路徑時(shí)基準(zhǔn)是當(dāng)前.pro文件所在的目錄不是構(gòu)建目錄。這在影子構(gòu)建時(shí)容易讓人困惑——你的源碼在/home/user/project構(gòu)建目錄在/home/user/project/build.pro里寫(xiě)INCLUDEPATH ./includeqmake會(huì)解析成/home/user/project/include而不是/home/user/project/build/include。這個(gè)行為其實(shí)是合理的但如果你習(xí)慣了某些IDE的“相對(duì)于構(gòu)建目錄”邏輯就會(huì)覺(jué)得別扭。第二個(gè)坑是路徑末尾不要加斜杠。INCLUDEPATH ./include/和INCLUDEPATH ./include在大多數(shù)情況下效果一樣但某些qmake版本或某些平臺(tái)下末尾斜杠可能導(dǎo)致路徑拼接時(shí)出現(xiàn)雙斜杠雖然編譯器通常能處理但看著不舒服也可能在某些工具鏈下出問(wèn)題。統(tǒng)一不加末尾斜杠是好習(xí)慣。第三個(gè)坑是順序問(wèn)題。INCLUDEPATH的搜索順序是按添加順序來(lái)的。如果你有兩個(gè)目錄下有同名頭文件先添加的目錄會(huì)被優(yōu)先搜索。這個(gè)特性有時(shí)候能救命——比如你想覆蓋某個(gè)第三方庫(kù)的頭文件把自己的目錄加在前面就行。但更多時(shí)候它是麻煩的來(lái)源——你以為用的是A版本的頭文件實(shí)際上編譯器找到了B版本的。我建議在.pro文件里給INCLUDEPATH加注釋標(biāo)明每個(gè)路徑的用途方便后續(xù)排查。# 項(xiàng)目自身頭文件 INCLUDEPATH $$PWD/src INCLUDEPATH $$PWD/include # 第三方庫(kù)頭文件 INCLUDEPATH $$PWD/thirdparty/json/include INCLUDEPATH $$PWD/thirdparty/spdlog/include這里用了$$PWD它是qmake的內(nèi)置變量表示當(dāng)前.pro文件所在目錄的絕對(duì)路徑。用$$PWD代替.的好處是路徑永遠(yuǎn)是絕對(duì)的不受構(gòu)建目錄影響也不會(huì)有相對(duì)路徑解析的歧義。我強(qiáng)烈建議在所有INCLUDEPATH和LIBS里都用$$PWD做前綴這是最穩(wěn)妥的做法。3.2 LIBS的配置細(xì)節(jié)與鏈接順序陷阱LIBS變量控制鏈接器的庫(kù)搜索路徑和要鏈接的庫(kù)。典型寫(xiě)法LIBS -L$$PWD/thirdparty/json/lib -ljsoncpp LIBS -L$$PWD/thirdparty/spdlog/lib -lspdlog-L指定庫(kù)文件所在目錄-l指定庫(kù)名不帶前綴和后綴。比如-ljsoncpp會(huì)讓鏈接器去找libjsoncpp.soLinux、libjsoncpp.a靜態(tài)庫(kù)、jsoncpp.libWindows或libjsoncpp.dylibmacOS。鏈接順序是這里最大的陷阱。GNU鏈接器Linux下處理庫(kù)的順序是從左到右如果庫(kù)A依賴(lài)庫(kù)B那么-lA必須出現(xiàn)在-lB前面。寫(xiě)反了就會(huì)報(bào)undefined reference。這個(gè)規(guī)則在Windows的MSVC鏈接器下不那么嚴(yán)格但在Linux和macOS下必須遵守。# 正確依賴(lài)方在前被依賴(lài)方在后 LIBS -lmyapp -lmybase # 錯(cuò)誤被依賴(lài)方在前可能導(dǎo)致undefined reference LIBS -lmybase -lmyapp如果庫(kù)之間有循環(huán)依賴(lài)可以用--start-group和--end-group包裹LIBS -Wl,--start-group -lA -lB -lC -Wl,--end-group但循環(huán)依賴(lài)本身通常是設(shè)計(jì)問(wèn)題能避免就避免。另一個(gè)細(xì)節(jié)是Windows下Debug和Release庫(kù)的區(qū)分。MSVC編譯的庫(kù)通常帶d后綴表示Debug版本比如mylibd.lib和mylib.lib。在.pro里可以用條件判斷CONFIG(debug, debug|release) { LIBS -L$$PWD/lib/debug -lmylibd } else { LIBS -L$$PWD/lib/release -lmylib }這個(gè)寫(xiě)法在跨平臺(tái)項(xiàng)目里很實(shí)用但要注意MinGW編譯器不一定遵循d后綴約定需要根據(jù)實(shí)際庫(kù)文件名調(diào)整。3.3 運(yùn)行時(shí)庫(kù)路徑的三種處理方式編譯鏈接都過(guò)了程序一運(yùn)行報(bào)“找不到動(dòng)態(tài)庫(kù)”這是運(yùn)行時(shí)路徑問(wèn)題。qmake本身不直接處理運(yùn)行時(shí)路徑但你可以通過(guò)幾種方式解決。方式一把動(dòng)態(tài)庫(kù)復(fù)制到可執(zhí)行文件旁邊。這是最簡(jiǎn)單粗暴的方法在Windows下特別有效因?yàn)閃indows默認(rèn)會(huì)在可執(zhí)行文件所在目錄搜索.dll。在.pro里可以加自定義構(gòu)建步驟自動(dòng)復(fù)制win32 { QMAKE_POST_LINK $$quote(cmd /c copy /y $$shell_path($$PWD/thirdparty/json/lib/jsoncpp.dll) $$shell_path($$OUT_PWD/release/)) }方式二設(shè)置rpathLinux和macOS。rpath是寫(xiě)在可執(zhí)行文件里的運(yùn)行時(shí)庫(kù)搜索路徑。qmake可以通過(guò)QMAKE_RPATHDIR設(shè)置unix:!macx { QMAKE_RPATHDIR $$PWD/thirdparty/json/lib } macx { QMAKE_RPATHDIR executable_path/../Frameworks }Linux下還可以用$ORIGIN表示可執(zhí)行文件所在目錄QMAKE_RPATHDIR $ORIGIN/lib這樣程序會(huì)去可執(zhí)行文件旁邊的lib目錄找動(dòng)態(tài)庫(kù)部署時(shí)把庫(kù)放在對(duì)應(yīng)位置就行。方式三設(shè)置環(huán)境變量。Linux下用LD_LIBRARY_PATHmacOS下用DYLD_LIBRARY_PATHWindows下用PATH。這種方式適合開(kāi)發(fā)調(diào)試階段不適合最終部署因?yàn)橐笥脩?hù)手動(dòng)配置環(huán)境變量。# Linux下臨時(shí)設(shè)置 export LD_LIBRARY_PATH/path/to/libs:$LD_LIBRARY_PATH ./myapp我個(gè)人的習(xí)慣是開(kāi)發(fā)階段用方式三快速驗(yàn)證確認(rèn)庫(kù)沒(méi)問(wèn)題后改用方式二rpath做正式配置Windows下用方式一。這樣既方便調(diào)試又保證部署時(shí)不需要額外配置。4. CMake下的路徑配置實(shí)操4.1 target_include_directories的作用域與最佳實(shí)踐CMake里配置頭文件路徑用target_include_directories比qmake的INCLUDEPATH多了一個(gè)作用域概念target_include_directories(myapp PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src ${CMAKE_CURRENT_SOURCE_DIR}/include ) target_include_directories(myapp PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/api ) target_include_directories(myapp INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/interface )PRIVATE表示這些路徑只用于編譯當(dāng)前target不傳遞給依賴(lài)它的其他target。PUBLIC表示既用于當(dāng)前target也傳遞給依賴(lài)它的target。INTERFACE表示不用于當(dāng)前target只傳遞給依賴(lài)它的target。這個(gè)機(jī)制在大型項(xiàng)目里非常有用。比如你寫(xiě)了一個(gè)庫(kù)mylib它的公開(kāi)頭文件在include/目錄私有頭文件在src/目錄。那么target_include_directories(mylib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src )這樣依賴(lài)mylib的其他target會(huì)自動(dòng)獲得include/的搜索路徑但不會(huì)獲得src/的路徑。封裝性很好。但這里有個(gè)常見(jiàn)誤區(qū)很多人把所有路徑都寫(xiě)成PUBLIC導(dǎo)致路徑污染。比如你把第三方庫(kù)的路徑寫(xiě)成PUBLIC所有依賴(lài)你的target都會(huì)去搜索那個(gè)第三方庫(kù)的路徑可能引發(fā)頭文件沖突。我的原則是只把確實(shí)需要暴露給外部的路徑設(shè)為PUBLIC其余一律PRIVATE。4.2 target_link_libraries的依賴(lài)傳遞與寫(xiě)法CMake里鏈接庫(kù)用target_link_librariestarget_link_libraries(myapp PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/json/lib/libjsoncpp.a ) target_link_libraries(myapp PRIVATE jsoncpp spdlog )可以直接寫(xiě)庫(kù)文件的完整路徑也可以寫(xiě)庫(kù)名讓CMake去搜索。寫(xiě)庫(kù)名時(shí)需要用link_directories指定搜索路徑link_directories(${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/json/lib) target_link_libraries(myapp PRIVATE jsoncpp)但link_directories的作用范圍是當(dāng)前目錄及子目錄而且不推薦在現(xiàn)代CMake中使用。更好的做法是用find_package或add_subdirectory引入第三方庫(kù)讓CMake自動(dòng)處理路徑。如果第三方庫(kù)沒(méi)有提供CMake支持可以手動(dòng)創(chuàng)建IMPORTEDtargetadd_library(jsoncpp STATIC IMPORTED) set_target_properties(jsoncpp PROPERTIES IMPORTED_LOCATION ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/json/lib/libjsoncpp.a INTERFACE_INCLUDE_DIRECTORIES ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/json/include ) target_link_libraries(myapp PRIVATE jsoncpp)這樣就把庫(kù)文件和頭文件路徑綁定在一起了用起來(lái)更干凈。4.3 運(yùn)行時(shí)路徑的CMake處理方案CMake設(shè)置rpath用INSTALL_RPATH和BUILD_RPATHset_target_properties(myapp PROPERTIES BUILD_RPATH ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/json/lib INSTALL_RPATH $ORIGIN/lib )BUILD_RPATH用于構(gòu)建階段的運(yùn)行INSTALL_RPATH用于安裝后的運(yùn)行。$ORIGIN在Linux下表示可執(zhí)行文件所在目錄macOS下用executable_path。Windows下CMake可以配置構(gòu)建后事件復(fù)制DLLadd_custom_command(TARGET myapp POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/json/lib/jsoncpp.dll $TARGET_FILE_DIR:myapp )這個(gè)寫(xiě)法比qmake的QMAKE_POST_LINK更清晰而且跨平臺(tái)兼容性更好。5. 路徑問(wèn)題排查實(shí)戰(zhàn)5.1 編譯期報(bào)錯(cuò)頭文件找不到的排查流程看到fatal error: xxx.h: No such file or directory按以下步驟排查第一步確認(rèn)頭文件是否真的存在于你配置的路徑下。有時(shí)候是文件根本沒(méi)下載全或者路徑拼寫(xiě)錯(cuò)了。我遇到過(guò)把include寫(xiě)成includes的情況找了半天才發(fā)現(xiàn)。第二步確認(rèn)INCLUDEPATH或target_include_directories是否真的生效了。qmake下可以運(yùn)行qmake -d查看詳細(xì)輸出CMake下可以用cmake --build . --verbose查看實(shí)際編譯命令。編譯命令里會(huì)包含-I參數(shù)看看你配置的路徑在不在里面。第三步檢查路徑分隔符和大小寫(xiě)。Windows下路徑不區(qū)分大小寫(xiě)Linux下區(qū)分。如果你在Windows下開(kāi)發(fā)代碼里寫(xiě)#include MyHeader.h但實(shí)際文件名是myheader.hWindows下能編譯Linux下就報(bào)錯(cuò)。第四步檢查是否有多個(gè)同名頭文件沖突。用編譯命令里的-I參數(shù)順序結(jié)合gcc -E -v查看頭文件搜索路徑的完整列表。5.2 鏈接期報(bào)錯(cuò)undefined reference的排查思路undefined reference to xxx說(shuō)明鏈接器找到了庫(kù)文件但庫(kù)里沒(méi)有這個(gè)符號(hào)?？赡艿脑驇?kù)文件版本不對(duì)比如鏈接了Release版但需要Debug版的符號(hào)庫(kù)文件架構(gòu)不對(duì)比如在64位項(xiàng)目里鏈接了32位庫(kù)鏈接順序問(wèn)題依賴(lài)方寫(xiě)在了被依賴(lài)方后面C符號(hào)修飾name mangling問(wèn)題比如C庫(kù)沒(méi)有用extern C包裹排查方法用nm命令查看庫(kù)文件里的符號(hào)nm -C libmylib.a | grep xxx如果符號(hào)存在但鏈接還是報(bào)錯(cuò)大概率是鏈接順序問(wèn)題。如果符號(hào)不存在說(shuō)明庫(kù)文件不對(duì)。5.3 運(yùn)行期報(bào)錯(cuò)動(dòng)態(tài)庫(kù)加載失敗的排查方法Linux下用ldd查看可執(zhí)行文件的動(dòng)態(tài)庫(kù)依賴(lài)ldd ./myapp輸出里如果有not found說(shuō)明對(duì)應(yīng)的庫(kù)找不到。然后用readelf -d ./myapp | grep RPATH查看rpath配置。macOS下用otool -L ./myapp查看依賴(lài)otool -l ./myapp | grep -A2 LC_RPATH查看rpath。Windows下用dumpbin /dependents myapp.exe查看依賴(lài)的DLL。這些工具能幫你快速定位是哪個(gè)庫(kù)找不到以及當(dāng)前的搜索路徑是什么。5.4 常見(jiàn)問(wèn)題速查表報(bào)錯(cuò)信息發(fā)生階段可能原因解決方法fatal error: xxx.h: No such file or directory編譯期INCLUDEPATH未配置或路徑錯(cuò)誤檢查INCLUDEPATH用$$PWD做前綴cannot find -lxxx鏈接期LIBS的-L路徑錯(cuò)誤或庫(kù)文件不存在檢查-L路徑和庫(kù)文件名undefined reference to xxx鏈接期鏈接順序錯(cuò)誤或庫(kù)版本不匹配調(diào)整鏈接順序檢查庫(kù)版本error while loading shared libraries運(yùn)行期動(dòng)態(tài)庫(kù)搜索路徑未配置設(shè)置rpath或LD_LIBRARY_PATHdyld: Library not loaded運(yùn)行期macOS rpath未配置設(shè)置QMAKE_RPATHDIR或INSTALL_RPATH程序啟動(dòng)閃退無(wú)報(bào)錯(cuò)運(yùn)行期Windows下DLL缺失用dumpbin檢查依賴(lài)復(fù)制DLL到exe目錄6. 幾個(gè)讓我印象深刻的踩坑經(jīng)歷6.1 影子構(gòu)建導(dǎo)致的相對(duì)路徑失效有一次我接手一個(gè)項(xiàng)目.pro文件里寫(xiě)的是INCLUDEPATH ./include。在源碼目錄下直接構(gòu)建沒(méi)問(wèn)題但換成影子構(gòu)建在單獨(dú)的build目錄里執(zhí)行qmake就報(bào)頭文件找不到。原因是qmake解析./include時(shí)基準(zhǔn)是.pro文件所在目錄但某些qmake版本在影子構(gòu)建時(shí)會(huì)把基準(zhǔn)解析成構(gòu)建目錄。后來(lái)我把所有相對(duì)路徑都改成$$PWD/include問(wèn)題徹底解決。這個(gè)經(jīng)歷讓我養(yǎng)成了一個(gè)習(xí)慣永遠(yuǎn)不在構(gòu)建配置里寫(xiě)裸的相對(duì)路徑一律用$$PWD或${CMAKE_CURRENT_SOURCE_DIR}做前綴。多打幾個(gè)字符省下的是幾小時(shí)的排查時(shí)間。6.2 鏈接順序引發(fā)的“靈異事件”一個(gè)項(xiàng)目在Windows下編譯鏈接都正常到了Linux下就報(bào)undefined reference。查了半天發(fā)現(xiàn)是鏈接順序問(wèn)題Windows的MSVC鏈接器對(duì)庫(kù)順序不敏感Linux的GNU鏈接器嚴(yán)格按順序解析。把LIBS里的庫(kù)順序調(diào)整了一下就好了。這件事教會(huì)我跨平臺(tái)項(xiàng)目要以最嚴(yán)格的平臺(tái)為準(zhǔn)來(lái)寫(xiě)配置。Linux的鏈接器最嚴(yán)格按它的規(guī)則寫(xiě)Windows和macOS基本都不會(huì)出問(wèn)題。6.3 macOS的rpath配置踩坑記macOS的rpath機(jī)制跟Linux不一樣它用rpath、executable_path、loader_path這幾個(gè)特殊變量。我第一次在macOS上配動(dòng)態(tài)庫(kù)路徑時(shí)按Linux的經(jīng)驗(yàn)設(shè)了QMAKE_RPATHDIR結(jié)果編譯鏈接都過(guò)運(yùn)行時(shí)報(bào)dyld: Library not loaded。后來(lái)查資料才知道m(xù)acOS需要在鏈接時(shí)加-rpath參數(shù)而且路徑要用executable_path開(kāi)頭。正確的配置是macx { QMAKE_LFLAGS -Wl,-rpath,executable_path/../Frameworks QMAKE_RPATHDIR executable_path/../Frameworks }這樣可執(zhí)行文件會(huì)去上級(jí)目錄的Frameworks文件夾找動(dòng)態(tài)庫(kù)。部署時(shí)把庫(kù)放在那個(gè)位置就行。7. 一些實(shí)用的配置建議7.1 項(xiàng)目目錄結(jié)構(gòu)規(guī)范一個(gè)清晰的目錄結(jié)構(gòu)能避免很多路徑問(wèn)題。我常用的結(jié)構(gòu)是project/ ├── src/ # 源碼 ├── include/ # 公開(kāi)頭文件 ├── thirdparty/ # 第三方庫(kù) │ ├── json/ │ │ ├── include/ │ │ └── lib/ │ └── spdlog/ │ ├── include/ │ └── lib/ ├── build/ # 構(gòu)建目錄影子構(gòu)建 └── myapp.pro第三方庫(kù)統(tǒng)一放在thirdparty下每個(gè)庫(kù)有獨(dú)立的include和lib子目錄。這樣INCLUDEPATH和LIBS的配置就很規(guī)整INCLUDEPATH $$PWD/include INCLUDEPATH $$PWD/thirdparty/json/include INCLUDEPATH $$PWD/thirdparty/spdlog/include LIBS -L$$PWD/thirdparty/json/lib -ljsoncpp LIBS -L$$PWD/thirdparty/spdlog/lib -lspdlog7.2 環(huán)境變量與構(gòu)建配置的分離不要把機(jī)器相關(guān)的路徑硬編碼在.pro或CMakeLists.txt里。比如/home/username/libs這種路徑換臺(tái)機(jī)器就失效了。可以用環(huán)境變量JSONCPP_DIR $$(JSONCPP_DIR) isEmpty(JSONCPP_DIR) { JSONCPP_DIR $$PWD/thirdparty/json } INCLUDEPATH $$JSONCPP_DIR/include LIBS -L$$JSONCPP_DIR/lib -ljsoncpp這樣默認(rèn)用項(xiàng)目?jī)?nèi)的第三方庫(kù)需要時(shí)可以通過(guò)環(huán)境變量覆蓋。CI/CD環(huán)境下特別有用。7.3 用qmake的system()做路徑檢查qmake支持在配置階段執(zhí)行shell命令可以用來(lái)做路徑存在性檢查!exists($$PWD/thirdparty/json/include/json/json.h) { error(jsoncpp headers not found. Please run setup script.) }這樣如果第三方庫(kù)沒(méi)準(zhǔn)備好qmake階段就會(huì)報(bào)錯(cuò)而不是等到編譯時(shí)才報(bào)頭文件找不到。錯(cuò)誤信息也更明確。路徑配置這件事說(shuō)到底就是“知道每個(gè)路徑在哪個(gè)階段起作用然后用最穩(wěn)妥的方式寫(xiě)”。我見(jiàn)過(guò)太多人在這上面反復(fù)踩坑其實(shí)只要把編譯期、鏈接期、運(yùn)行期這三個(gè)階段分清楚再記住$$PWD和${CMAKE_CURRENT_SOURCE_DIR}這兩個(gè)“萬(wàn)能前綴”大部分問(wèn)題都能避免。剩下那些跨平臺(tái)的差異遇到一次記一次慢慢就形成條件反射了。