構(gòu)建工具開發(fā)工具CLI【免費下載鏈接】CMakeMirror of CMake upstream repository項目地址https://gitcode.com/gh_mirrors/cm/CMake點擊查看免費下載本指南以 CMake 倉庫中的 debug-properties.rst 為核心系統(tǒng)講解CMakePresets.json中configurePresets[].debug對象的三個布爾字段——output、tryCompile、find——各自的語義、與命令行選項的等價關(guān)系、繼承規(guī)則以及底層解析與執(zhí)行機制。讀完本文你將能在不修改 CMakeLists.txt 的前提下僅通過預(yù)設(shè)文件一鍵開啟 CMake 運行時診斷、保留 try_compile 臨時文件、以及追蹤 find 系列命令的搜索過程并與cmake --debug-output、--debug-trycompile、--debug-find等命令行用法自如互換。一、debug 對象在 configurePresets 中的位置在 CMake 的預(yù)設(shè)Presets體系中configurePresets數(shù)組中的每個元素都可以攜帶一個可選的debug對象用于集中指定調(diào)試選項。在 configurePresets-properties.rst 中該字段被定義為debug—— An optional object specifying debug options. The object may contain the following fields.從倉庫中的 schema.yaml 看debug的類型約束為object其unevaluatedProperties為false即只允許出現(xiàn)下文約定的三個字段出現(xiàn)任何未知鍵都會被 JSON Schema 校驗器拒絕outputbooleantryCompilebooleanfindboolean值得注意的版本線索在 schema.yaml 中與同級的trace標(biāo)注since: 7不同debug對象沒有since標(biāo)注。從源碼結(jié)構(gòu)看這意味著它是 configure preset 自 schema v1 起便存在的早期字段幾乎所有支持 Presets 的 CMake 版本都能識別它。與之形成對比的是trace、condition、toolchainFile等字段分別有明確的版本引入標(biāo)記。二、三個字段逐一拆解語義、命令行等價與源碼實現(xiàn)debug對象中的每一個字段都是可選的布爾值設(shè)置true與在命令行中傳遞對應(yīng)的開關(guān)等價。下面分別展開。2.1 debug.output —— 等價于 --debug-output語義可選的布爾值。設(shè)置為true等價于在命令行傳入--debug-output。--debug-output在 cmake.1.rst 中的完整定義是Put cmake in a debug mode. Print extra information during the cmake run like stack traces withmessage(SEND_ERROR)calls.也就是說開啟后 CMake 在運行期間會輸出額外的診斷信息包括message(SEND_ERROR)調(diào)用時的堆棧軌跡stack trace用于追蹤錯誤產(chǎn)生的調(diào)用鏈。源碼證據(jù)在 cmake.cxx 中命令行參數(shù)--debug-output被解析后調(diào)用state-SetDebugOutputOn(true)而在應(yīng)用預(yù)設(shè)時cmake.cxx 中expandedPreset-DebugOutput true會調(diào)用同一個SetDebugOutputOn(true)。兩條路徑殊途同歸驗證了預(yù)設(shè)字段 命令行選項的等價關(guān)系。該標(biāo)志在運行期如何發(fā)揮作用從 cmMakefile.cxx 與 cmMakefile.cxx 看GetDebugOutput()被用于決定是否打印額外的調(diào)試消息例如文件加載、配置相關(guān)日志在 cmFileCommand.cxx 中cm-GetDebugOutput() || cm-GetTrace()的組合還控制著file()命令相關(guān)操作的額外輸出。此外CMakeSetupDialog.cxx 與 QCMake.cxx 表明 CMake GUI 也提供對應(yīng)的開關(guān)最終同樣落到cmake實例的SetDebugOutputOn。2.2 debug.tryCompile —— 等價于 --debug-trycompile語義可選的布爾值。設(shè)置為true等價于在命令行傳入--debug-trycompile。--debug-trycompile在 cmake.1.rst 中的完整定義如下Do not delete the files and directories created fortry_compile/try_runcalls. This is useful in debugging failed checks. Note that some uses oftry_compilemay use the same build tree, which will limit the usefulness of this option if a project executes more than onetry_compile. For example, such uses may change results as artifacts from a previous try-compile may cause a different test to either pass or fail incorrectly. This option is best used only when debugging. (With respect to the preceding, thetry_runcommand is effectively atry_compile. Any combination of the two is subject to the potential issues described.)versionadded:: 3.25— When this option is enabled, every try-compile check prints a log message reporting the directory in which the check is performed.源碼證據(jù)命令行解析位于 cmake.cxx調(diào)用DebugTryCompileOn()預(yù)設(shè)應(yīng)用位于 cmake.cxxexpandedPreset-DebugTryCompile true時同樣調(diào)用DebugTryCompileOn()。實際消費該標(biāo)志的是 try-compile 的核心實現(xiàn) cmCoreTryCompile.cxx當(dāng)GetDebugTryCompile()為真時為try_compile/try_run創(chuàng)建的目錄與文件不會被清理方便開發(fā)者進入該目錄檢查編譯器實際執(zhí)行的命令與產(chǎn)物。實戰(zhàn)價值當(dāng)check_*系列如CheckCSourceCompiles、CheckSymbolExists或項目內(nèi)顯式try_compile失敗且難以定位原因時開啟debug.tryCompile即可凍結(jié)現(xiàn)場。同時注意官方文檔的告誡該選項僅建議在調(diào)試時使用因為多次 try-compile 可能共享同一構(gòu)建樹遺留產(chǎn)物可能污染后續(xù)檢查結(jié)果導(dǎo)致假陽性或假陰性。2.3 debug.find —— 等價于 --debug-find語義可選的布爾值。設(shè)置為true等價于在命令行傳入--debug-find。--debug-find在 cmake.1.rst 中的完整定義如下Put cmake find commands in a debug mode. Print extra find call information during the cmake run to standard error. Output is designed for human consumption and not for parsing. See also theCMAKE_FIND_DEBUG_MODEvariable for debugging a more local part of the project.版本信息--debug-find在 CMake 3.17 加入文檔標(biāo)注versionadded:: 3.17。源碼證據(jù)命令行解析位于 cmake.cxx調(diào)用SetDebugFindOutput(true)預(yù)設(shè)應(yīng)用位于 cmake.cxx。在 find 命令的公共實現(xiàn) cmFindCommon.cxx 中GetDebugFindPkgMode() || ...之類的條件驅(qū)動 find 調(diào)試輸出的開關(guān)cmMakefile.cxx 中還有一個DebugFindPkgRAII輔助類在進入find_package(pkg)調(diào)用時根據(jù)包的名稱臨時切換調(diào)試模式退出時恢復(fù)舊值從而實現(xiàn)只調(diào)試指定包的局部化能力。實戰(zhàn)價值當(dāng)find_package、find_library、find_path、find_program、find_file等找不到目標(biāo)、或找到了錯誤版本時開啟debug.find會把每個 find 調(diào)用的搜索路徑、命中/未命中的判定過程輸出到標(biāo)準(zhǔn)錯誤stderr輸出面向人類閱讀而非機器解析。若只想調(diào)試項目中的局部區(qū)域官方還提供了CMAKE_FIND_DEBUG_MODE變量作為更細(xì)粒度的替代。三、三個調(diào)試字段的繼承與合并規(guī)則debug對象遵循 configure preset 的通用inherits繼承機制。在 cmCMakePresetsGraph.cxx 中展開預(yù)設(shè)時對這三個字段分別執(zhí)行了InheritOptionalValue(preset.DebugOutput, parent.DebugOutput)等調(diào)用——注意它們是逐字段獨立繼承的若子預(yù)設(shè)未顯式設(shè)置某字段則繼承父預(yù)設(shè)inherits鏈上對應(yīng)字段的值若子預(yù)設(shè)顯式設(shè)置則以子預(yù)設(shè)為準(zhǔn)多個父預(yù)設(shè)提供沖突值時inherits數(shù)組靠前的預(yù)設(shè)優(yōu)先該規(guī)則在 configurePresets-properties.rst 中有明確定義。這意味著你可以把公共的調(diào)試開關(guān)放在一個hidden: true的基預(yù)設(shè)中再讓具體配置預(yù)設(shè)繼承它無需在每個預(yù)設(shè)里重復(fù)書寫。字段解析層面的對應(yīng)證據(jù)在 cmCMakePresetsGraphReadJSONConfigurePresets.cxxPresetDebugHelper通過Bind(output_s, ...)、Bind(tryCompile_s, ...)、Bind(find_s, ...)將 JSON 鍵綁定到ConfigurePreset::DebugOutput、DebugTryCompile、DebugFind三個可選布爾成員類型定義見 cmCMakePresetsGraph.h并且三個鍵均允許缺省最后一個false參數(shù)表示非必需鍵。隨后該 Helper 被整體綁定到debug鍵下cmCMakePresetsGraphReadJSONConfigurePresets.cxx。四、完整可運行的配置示例下面的示例在 example.json 的骨架之上加入debug對象展示三種常見形態(tài)。將以下內(nèi)容寫入項目根目錄的CMakePresets.json后執(zhí)行cmake --preset debug-on即可同時獲得三路診斷輸出。{ version: 10, configurePresets: [ { name: base, hidden: true, generator: Ninja, binaryDir: ${sourceDir}/build/${presetName}, debug: { output: true, tryCompile: true, find: true } }, { name: debug-on, inherits: base, displayName: 全量調(diào)試配置, description: 開啟 output/tryCompile/find 全部調(diào)試開關(guān) }, { name: find-only, inherits: base, displayName: 僅追蹤 find 命令, description: 關(guān)閉前兩項僅保留 find 調(diào)試, debug: { output: false, tryCompile: false } } ] }要點說明debug-on完全繼承base的三個開關(guān)等價于執(zhí)行cmake --debug-output --debug-trycompile --debug-find --preset debug-on未顯式指定的generator、binaryDir同樣繼承自base。find-only在繼承基礎(chǔ)上顯式將output、tryCompile置為false進行覆蓋最終僅保留find: true。由于三個字段均為可選即使完全不寫debug對象預(yù)設(shè)也完全合法——調(diào)試開關(guān)默認(rèn)關(guān)閉與命令行不傳對應(yīng)參數(shù)的行為一致。五、調(diào)試策略與注意事項5.1 何時使用 debug.output當(dāng)message(SEND_ERROR)觸發(fā)、或需要理解 CMake 配置階段的內(nèi)部運行軌跡時開啟。它與--trace對應(yīng)trace預(yù)設(shè)對象見 schema.yaml的區(qū)別在于debug.output輸出的是運行診斷與堆棧信息而trace輸出的是所有命令調(diào)用的調(diào)用軌跡。二者可以組合使用各自側(cè)重不同。5.2 何時使用 debug.tryCompile針對try_compile/try_run檢查失敗時開啟。開啟后每次檢查還會額外打印一條日志報告檢查發(fā)生在哪個目錄該行為在 cmake.1.rst 中標(biāo)注為 3.25 引入。調(diào)試完成后務(wù)必關(guān)閉因為遺留的構(gòu)建產(chǎn)物可能干擾后續(xù)檢查的判定結(jié)果。5.3 何時使用 debug.find 及其局限針對find_*系列命令找不到或找錯目標(biāo)時開啟。若想進一步縮小范圍CMake 還提供--debug-find-pkgpkg[,...]與--debug-find-varvar[,...]兩個限定版命令行選項見 cmake.1.rst均于 3.23 加入分別限定到指定包名或指定結(jié)果變量名——不過它們目前沒有對應(yīng)的 preset 字段只能通過命令行或CMAKE_FIND_DEBUG_MODE變量使用。預(yù)設(shè)層的debug.find是全局開關(guān)輸出寫到標(biāo)準(zhǔn)錯誤注意不要將其輸出接入需要機器解析的管道。六、總結(jié)預(yù)設(shè)與命令行的一一對應(yīng)debug 字段類型默認(rèn)值等價命令行選項引入版本命令行源碼落點outputbooleanfalse--debug-output早期即存在cmake.cxxtryCompilebooleanfalse--debug-trycompile日志消息 3.25 增強cmCoreTryCompile.cxxfindbooleanfalse--debug-find3.17cmake.cxxdebug對象是 configure preset 中把調(diào)試意圖寫進配置文件的標(biāo)準(zhǔn)化入口。通過繼承機制團隊可以把整套調(diào)試開關(guān)沉淀在共享基預(yù)設(shè)中按需覆蓋配合 schema.json 提供的 JSON SchemaIDE 中還能獲得字段級的校驗與自動補全。理解debug三個字段與命令行選項的等價關(guān)系、以及它們最終如何驅(qū)動cmCoreTryCompile、cmFindCommon等底層實現(xiàn)是高效排查 CMake 配置階段問題的關(guān)鍵一步。贊分享構(gòu)建工具開發(fā)工具CLI【免費下載鏈接】CMakeMirror of CMake upstream repository項目地址https://gitcode.com/gh_mirrors/cm/CMake點擊查看免費下載相關(guān)推薦Ladybird 瀏覽器的 VS Code 開發(fā)環(huán)境配置CMake Presets、clangd 索引、任務(wù)與調(diào)試指南Ladybird 瀏覽器的 VS Code 開發(fā)環(huán)境配置CMake Presets、clangd 索引、任務(wù)與調(diào)試指南 本文基于 Ladybird 倉庫官方文前端WebAssemblyFIND配置參數(shù)詳解從基礎(chǔ)設(shè)置到高級調(diào)優(yōu)FIND配置參數(shù)詳解從基礎(chǔ)設(shè)置到高級調(diào)優(yōu) FINDFramework for Internal Navigation and Discovery是一個高精后端機器學(xué)習(xí)物聯(lián)網(wǎng)Frigate 對象檢測調(diào)試完全指南歷史標(biāo)注回放、Debug Replay 與手動 Dummy Camera 配置Frigate 對象檢測調(diào)試完全指南歷史標(biāo)注回放、Debug Replay 與手動 Dummy Camera 配置 本指南聚焦 Frigate NVR 中最實人工智能計算機視覺音視頻上一篇Slang光線追蹤加速結(jié)構(gòu)BVH構(gòu)建與遍歷優(yōu)化下一篇Voilà安全防護機制保護Jupyter應(yīng)用的5個關(guān)鍵策略創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考