設定 C/C++ 偵錯

Name: Visual Studio Code
Author: Microsoft

launch.json 檔案用於設定 Visual Studio Code 中的偵錯工具。

Visual Studio Code 會產生一個 launch.json 檔案 (在專案的 .vscode 資料夾下)，其中包含幾乎所有必要的資訊。若要開始偵錯，您需要填寫 program 欄位，其中包含您計畫偵錯的可執行檔路徑。對於啟動和附加 (如果您計畫隨時附加至執行中的執行個體) 設定，都必須指定此路徑。

產生的檔案包含兩個區段，一個區段設定啟動偵錯，另一個區段設定附加偵錯。

設定 VS Code 的偵錯行為

設定或變更下列選項以控制 VS Code 在偵錯期間的行為

program (必要)

指定偵錯工具將啟動或附加的可執行檔完整路徑。偵錯工具需要此位置才能載入偵錯符號。

symbolSearchPath

告知 Visual Studio Windows 偵錯工具要搜尋符號 (.pdb) 檔案的路徑。以分號分隔多個路徑。例如："C:\\Symbols;C:\\SymbolDir2"。

requireExactSource

一個選用旗標，告知 Visual Studio Windows 偵錯工具需要目前的原始程式碼與 pdb 相符。

additionalSOLibSearchPath

告知 GDB 或 LLDB 要搜尋 .so 檔案的路徑。以分號分隔多個路徑。例如："/Users/user/dir1;/Users/user/dir2"。

externalConsole

僅在啟動 debuggee 時使用。對於 attach，此參數不會變更 debuggee 的行為。

Windows：設定為 true 時，將會產生外部主控台。設定為 false 時，將會使用 VS Code 的 integratedTerminal。
Linux：設定為 true 時，將會通知 VS Code 產生外部主控台。設定為 false 時，將會使用 VS Code 的 integratedTerminal。
macOS：設定為 true 時，將會透過 lldb-mi 產生外部主控台。設定為 false 時，輸出可以在 VS Code 的 debugConsole 中看到。由於 lldb-mi 中的限制，因此不支援 integratedTerminal。

avoidWindowsConsoleRedirection

為了支援 Windows 上搭配 gdb 的 VS Code Integrated Terminal，擴充功能會將主控台重新導向命令新增至 debuggee 的引數，以讓主控台輸入和輸出顯示在 integrated terminal 中。將此選項設定為 true 將會停用它。

logging

選用旗標，用於判斷應該將哪些類型的訊息記錄到偵錯主控台中。

exceptions：選用旗標，用於判斷是否應將例外狀況訊息記錄到偵錯主控台中。預設值為 true。
moduleLoad：選用旗標，用於判斷是否應將模組載入事件記錄到偵錯主控台中。預設值為 true。
programOutput：選用旗標，用於判斷是否應將程式輸出記錄到偵錯主控台中。預設值為 true。
engineLogging：選用旗標，用於判斷是否應將診斷引擎記錄記錄到偵錯主控台中。預設值為 false。
trace：選用旗標，用於判斷是否應將診斷配接器命令追蹤記錄到偵錯主控台中。預設值為 false。
traceResponse：選用旗標，用於判斷是否應將診斷配接器命令和回應追蹤記錄到偵錯主控台中。預設值為 false。

visualizerFile

偵錯時要使用的 .natvis 檔案。如需如何建立 Natvis 檔案的資訊，請參閱建立原生物件的自訂檢視。

showDisplayString

當指定 visualizerFile 時，showDisplayString 將啟用顯示字串。開啟此選項可能會導致偵錯期間效能變慢。

範例

{
  "name": "C++ Launch (Windows)",
  "type": "cppvsdbg",
  "request": "launch",
  "program": "C:\\app1\\Debug\\app1.exe",
  "symbolSearchPath": "C:\\Symbols;C:\\SymbolDir2",
  "externalConsole": true,
  "logging": {
    "moduleLoad": false,
    "trace": true
  },
  "visualizerFile": "${workspaceFolder}/my.natvis",
  "showDisplayString": true
}

設定目標應用程式

下列選項可讓您在目標應用程式啟動時修改其狀態

args

要在程式啟動時傳遞給程式的命令列引數 JSON 陣列。範例 ["arg1", "arg2"]。如果您要逸出字元，則需要雙重逸出。例如，["{\\\"arg1\\\": true}"] 將會傳送 {"arg1": true} 到您的應用程式。

cwd

設定偵錯工具啟動之應用程式的工作目錄。

environment

要新增至程式環境的環境變數。範例：[ { "name": "config", "value": "Debug" } ]，而不是 [ { "config": "Debug" } ]。

範例

{
  "name": "C++ Launch",
  "type": "cppdbg",
  "request": "launch",
  "program": "${workspaceFolder}/a.out",
  "args": ["arg1", "arg2"],
  "environment": [{ "name": "config", "value": "Debug" }],
  "cwd": "${workspaceFolder}"
}

自訂 GDB 或 LLDB

您可以透過設定下列選項來變更 GDB 或 LLDB 的行為

MIMode

指出 VS Code 將連線到的偵錯工具。必須設定為 gdb 或 lldb。這是針對每個作業系統預先設定的，可以視需要變更。

miDebuggerPath

偵錯工具的路徑 (例如 gdb)。當僅指定可執行檔時，它將會在作業系統的 PATH 變數中搜尋偵錯工具 (Linux 和 Windows 上的 GDB，OS X 上的 LLDB)。

miDebuggerArgs

要傳遞至偵錯工具的其他引數 (例如 gdb)。

stopAtEntry

如果設定為 true，偵錯工具應在目標的進入點停止 (在附加時會忽略)。預設值為 false。

stopAtConnect

如果設定為 true，偵錯工具應在連線到目標之後停止。如果設定為 false，偵錯工具將在連線後繼續執行。預設值為 false。

setupCommands

要在 GDB 或 LLDB 中執行的命令 JSON 陣列，以進行設定。範例："setupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }]。

customLaunchSetupCommands

如果提供，這會將用於啟動目標的預設命令取代為其他命令。例如，這可以是 "-target-attach"，以便附加至目標進程。空的命令清單會將啟動命令取代為無，如果偵錯工具是以命令列選項的形式提供啟動選項，則這會很有用。範例："customLaunchSetupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }]。

launchCompleteCommand

在偵錯工具完全設定完成後要執行的命令，以便讓目標進程執行。允許的值為 "exec-run"、"exec-continue"、"None"。預設值為 "exec-run"。

範例

{
  "name": "C++ Launch",
  "type": "cppdbg",
  "request": "launch",
  "program": "${workspaceFolder}/a.out",
  "stopAtEntry": false,
  "customLaunchSetupCommands": [
    { "text": "target-run", "description": "run target", "ignoreFailures": false }
  ],
  "launchCompleteCommand": "exec-run",
  "linux": {
    "MIMode": "gdb",
    "miDebuggerPath": "/usr/bin/gdb"
  },
  "osx": {
    "MIMode": "lldb"
  },
  "windows": {
    "MIMode": "gdb",
    "miDebuggerPath": "C:\\MinGw\\bin\\gdb.exe"
  }
}

symbolLoadInfo

loadAll：如果為 true，則會載入所有程式庫的符號，否則不會載入任何 solib 符號。由 ExceptionList 修改。預設值為 true。
exceptionList：以分號 ; 分隔的檔案名稱清單 (允許使用萬用字元)。修改 LoadAll 的行為。如果 LoadAll 為 true，則不要載入符合清單中任何名稱的程式庫符號。否則，僅載入符合的程式庫符號。範例："foo.so;bar.so"

偵錯傾印檔案

C/C++ 擴充功能可在 Windows 上啟用偵錯傾印檔案，並在 Linux 和 OS X 上啟用核心傾印檔案。

dumpPath

如果您想要偵錯 Windows 傾印檔案，請將此設定為傾印檔案的路徑，以在 launch 設定中開始偵錯。

coreDumpPath

要針對指定程式偵錯的核心傾印檔案完整路徑。將此設定為核心傾印檔案的路徑，以在 launch 設定中開始偵錯。注意：MinGw 不支援核心傾印偵錯。

遠端偵錯或使用本機偵錯伺服器進行偵錯

miDebuggerServerAddress

要連線以進行遠端偵錯的偵錯工具伺服器 (例如 gdbserver) 網路位址 (範例：localhost:1234)。

debugServerPath

要啟動的偵錯伺服器完整路徑。

debugServerArgs

偵錯伺服器的引數。

serverStarted

要在偵錯伺服器輸出中尋找的伺服器啟動模式。支援正則運算式。

filterStdout

如果設定為 true，則在 stdout 串流中搜尋伺服器啟動模式，並將 stdout 記錄到偵錯輸出。預設值為 true。

filterStderr

如果設定為 true，則在 stderr 串流中搜尋伺服器啟動模式，並將 stderr 記錄到偵錯輸出。預設值為 false。

serverLaunchTimeout

偵錯工具等待 debugServer 啟動的逾時時間 (毫秒)。預設值為 10000。

pipeTransport

如需附加至遠端進程的相關資訊，例如偵錯 Docker 容器中的進程，請參閱管道傳輸設定文章。

hardwareBreakpoints

如果提供，這會明確控制遠端目標的硬體中斷點行為。如果 require 設定為 true，則一律使用硬體中斷點。預設值為 false。limit 是可用的硬體中斷點數量的選用限制，僅在 require 為 true 且 limit 大於 0 時強制執行。預設值為 0。範例："hardwareBreakpoints": { require: true, limit: 6 }。

其他屬性

processId

預設為 ${command:pickProcess}，這會顯示偵錯工具可以附加的可用進程清單。我們建議您保留此預設值，但可以將此屬性明確設定為偵錯工具要附加的特定進程識別碼。

request

指出設定區段是否旨在 launch 程式或 attach 至已在執行的執行個體。

targetArchitecture

已過時 此選項已不再需要，因為目標架構會自動偵測。

type

指出正在使用的基礎偵錯工具。使用 Visual Studio Windows 偵錯工具時必須為 cppvsdbg，使用 GDB 或 LLDB 時必須為 cppdbg。建立 launch.json 檔案時，會自動將此設定為正確的值。

sourceFileMap

這允許將原始程式碼的編譯時期路徑對應至本機原始程式碼位置。它是一個索引鍵/值組的物件，將會解析第一個字串比對的路徑。(範例："sourceFileMap": { "/mnt/c": "c:\\" } 將會對應偵錯工具傳回的任何以 /mnt/c 開頭的路徑，並將其轉換為 c:\\。您可以在物件中有多個對應，但它們將依提供的順序處理。)

環境變數定義檔

環境變數定義檔是一個簡單的文字檔，其中包含索引鍵值組，格式為 environment_variable=value，並使用 # 作為註解。不支援多行值。

cppvsdbg 偵錯工具設定也包含 envFile 屬性，可讓您輕鬆設定用於偵錯目的的變數。

例如

project.env 檔案:

# project.env

# Example environment with key as 'MYENVRIONMENTPATH' and value as C:\\Users\\USERNAME\\Project
MYENVRIONMENTPATH=C:\\Users\\USERNAME\\Project

# Variables with spaces
SPACED_OUT_PATH="C:\\This Has Spaces\\Project"

符號選項

symbolOptions 元素允許自訂偵錯工具搜尋符號的方式。範例

    "symbolOptions": {
        "searchPaths": [
            "C:\\src\\MyOtherProject\\bin\\debug",
            "https://my-companies-symbols-server"
        ],
        "searchMicrosoftSymbolServer": true,
        "cachePath": "%TEMP%\\symcache",
        "moduleFilter": {
            "mode": "loadAllButExcluded",
            "excludedModules": [ "DoNotLookForThisOne*.dll" ]
        }
    }

屬性

searchPaths：要搜尋 .pdb 檔案的符號伺服器 URL (範例：https://msdl.microsoft.com/download/symbols) 或目錄 (範例：/build/symbols) 陣列。除了預設位置 (模組旁邊和 pdb 最初放置的路徑) 之外，還會搜尋這些目錄。

searchMicrosoftSymbolServer：如果為 true，Microsoft 符號伺服器 (https://msdl.microsoft.com/download/symbols) 會新增至符號搜尋路徑。如果未指定，此選項預設為 false。

cachePath"：應該快取從符號伺服器下載的符號的目錄。如果未指定，偵錯工具將預設為 %TEMP%\SymbolCache。

moduleFilter.mode：此值為 "loadAllButExcluded" 或 "loadOnlyIncluded"。在 "loadAllButExcluded" 模式中，偵錯工具會載入所有模組的符號，除非模組位於 'excludedModules' 陣列中。在 "loadOnlyIncluded" 模式中，偵錯工具不會嘗試載入任何模組的符號，除非它位於 'includedModules' 陣列中，或者透過 'includeSymbolsNextToModules' 設定包含在內。

`"loadAllButExcluded"` 模式的屬性

moduleFilter.excludedModules：偵錯工具不應載入符號的模組陣列。支援萬用字元 (範例：MyCompany.*.dll)。

`"loadOnlyIncluded"` 模式的屬性

moduleFilter.includedModules：偵錯工具應載入符號的模組陣列。支援萬用字元 (範例：MyCompany.*.dll)。

moduleFilter.includeSymbolsNextToModules：如果為 true，對於任何不在 'includedModules' 陣列中的模組，偵錯工具仍會檢查模組本身和啟動可執行檔旁邊，但不會檢查符號搜尋清單上的路徑。此選項預設為 'true'。

6/10/2021