C/C++ デバッグの構成

Name: Visual Studio Code
Author: Microsoft

launch.json ファイルは、Visual Studio Code でデバッガーを構成するために使用されます。

Visual Studio Code は、必要な情報のほとんどを含む launch.json ファイル (プロジェクトの .vscode フォルダーの下) を生成します。デバッグを開始するには、デバッグする実行可能ファイルへのパスを program フィールドに入力する必要があります。これは、起動構成とアタッチ構成 (後で実行中のインスタンスにアタッチする場合) の両方で指定する必要があります。

生成されたファイルには、起動のデバッグを構成するセクションと、アタッチのデバッグを構成するセクションの 2 つが含まれています。

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

デバッグ対象を起動する場合にのみ使用されます。attach の場合、このパラメーターはデバッグ対象の動作を変更しません。

Windows: true に設定すると、外部コンソールが生成されます。false に設定すると、VS Code の integratedTerminal が使用されます。
Linux: true に設定すると、VS Code に外部コンソールを生成するように通知します。false に設定すると、VS Code の integratedTerminal が使用されます。
macOS: true に設定すると、lldb-mi を介して外部コンソールが生成されます。false に設定すると、出力は VS Code のデバッグコンソールに表示されます。lldb-mi の制限により、integratedTerminal のサポートは利用できません。

avoidWindowsConsoleRedirection

Windows 上の gdb で VS Code の統合ターミナルをサポートするために、拡張機能はコンソール入力と出力が統合ターミナルに表示されるように、コンソールリダイレクトコマンドをデバッグ対象の引数に追加します。このオプションを 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": "ターゲットを実行", "ignoreFailures": false }]。

customLaunchSetupCommands

指定した場合、これはターゲットを起動するために使用されるデフォルトコマンドを他のコマンドに置き換えます。たとえば、ターゲットプロセスにアタッチするために "-target-attach" にすることができます。空のコマンドリストは、起動コマンドを何もないものに置き換えます。これは、デバッガーにコマンドラインオプションとして起動オプションが提供されている場合に役立ちます。例: "customLaunchSetupCommands": [ { "text": "target-run", "description": "ターゲットを実行", "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 ストリームで server-started パターンを検索し、stdout をデバッグ出力にログ記録します。デフォルト値は true です。

filterStderr

true に設定すると、stderr ストリームで server-started パターンを検索し、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} であり、デバッガーがアタッチできる使用可能なプロセスのリストが表示されます。このデフォルトのままにしておくことをお勧めしますが、プロパティをデバッガーがアタッチする特定のプロセス ID に明示的に設定できます。

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' 設定によって含まれていない限り、デバッガーは ANY モジュールのシンボルをロードしようとしません。

`"loadAllButExcluded"` モードのプロパティ

moduleFilter.excludedModules: デバッガーがシンボルをロードしないモジュールの配列。ワイルドカード (例: MyCompany.*.dll) がサポートされています。

`"loadOnlyIncluded"` モードのプロパティ

moduleFilter.includedModules: デバッガーがシンボルをロードするモジュールの配列。ワイルドカード (例: MyCompany.*.dll) がサポートされています。

moduleFilter.includeSymbolsNextToModules: true の場合、'includedModules' 配列に含まれていないモジュールについては、デバッガーはモジュール自体の隣と起動実行可能ファイルの隣をチェックしますが、シンボル検索リストのパスはチェックしません。このオプションはデフォルトで 'true' です。

6/10/2021