CMake デバッグセッションを構成する

[アーティクル]
10/28/2023

CMake のネイティブサポートは Visual Studio 2017 以降で利用できます。これらのバージョンのドキュメントを表示するには、この記事の Visual Studio バージョン セレクターコントロールを Visual Studio 2017 以降に設定します。このページの目次の一番上にあります。

すべての実行可能な CMake ターゲットが、ツールバーの [スタートアップアイテム] ドロップダウンに表示されます。 1 つを選択してデバッグセッションを開始し、デバッガーを起動します。

[CMake スタートアップ項目] ドロップダウンのスクリーンショット。

ソリューションエクスプローラーからデバッグセッションを開始することもできます。まず、[ソリューションエクスプローラー] ウィンドウで [CMake ターゲットビュー] に切り替えます。

[CMake ターゲットビュー] メニューのスクリーンショット。

次に、実行可能ファイルを右クリックして [デバッグ] を選択します。このコマンドにより、アクティブな構成に基づいて、選択したターゲットのデバッグが自動的に開始されます。

CMake ターゲットビューのデバッグオプションメニューのスクリーンショット。

Visual Studio 2022 バージョン 17.6 以降では、CMakeLists.txt ファイルでデバッグセッションを開始することもできます。そのためには、CMakeLists.txt ファイルにブレークポイントを設定し、Project ドロップダウンから Configure Project with CMake Debugger を実行します。

[CMake デバッガー] ドロップダウンのスクリーンショット。

デバッガー設定をカスタマイズする

プロジェクト内の任意の実行可能な CMake ターゲットのデバッガー設定をカスタマイズできます。これらの設定は、プロジェクトルートの .vs フォルダー内にある launch.vs.json という構成ファイル内にあります。起動構成ファイルは、デバッグ設定の詳細を構成して保存できるため、ほとんどのデバッグシナリオで役立ちます。このファイルには 3 つのエントリポイントがあります。

[デバッグ] メニュー: メインメニューから [デバッグ] > [${activeDebugTarget} のデバッグおよび起動の設定] を選択し、アクティブなデバッグターゲットに固有のデバッグ構成をカスタマイズします。デバッグターゲットを選択していない場合、このオプションはグレー表示されます。

ターゲットビュー: ソリューションエクスプローラーの Targets ビューに移動します。次に、デバッグターゲットを右クリックし、[Add Debug Configuration]$デバッグ構成の追加$ を選び、選択したターゲットに固有のデバッグ構成をカスタマイズします。

ターゲットのショートカットメニューにあるデバッグ構成の追加コマンドのスクリーンショット。

ルート CMakeLists.txt: ルート CMakeLists.txt を右クリックし、 デバッグ構成の追加 を選択して デバッガーの選択 ダイアログボックスを開きます。このダイアログでは、"すべての" 種類のデバッグ構成を追加できますが、projectTarget プロパティを使用して、呼び出す CMake ターゲットを手動で指定する必要があります。

[デバッガーの選択] ダイアログボックスのスクリーンショット。

launch.vs.json ファイルを編集して、任意の数の CMake ターゲットに対してデバッグ構成を作成できます。このファイルを保存すると、Visual Studio によって [スタートアップアイテム] ドロップダウンに新しい構成ごとにエントリが作成されます。

CMakeSettings.json のキーを参照する

CMakeSettings.json ファイル内の任意のキーを参照するには、launch.vs.json内でそのキーの先頭に cmake. を追加します。次に示す簡単な launch.vs.json ファイルの例では、現在選択されている構成に対して、CMakeSettings.json ファイル内の remoteCopySources キーの値を取得しています。

{
  "version": "0.2.1",
  "configurations": [
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "CMakeHelloWorld.exe (Debug\\CMakeHelloWorld.exe)",
      "name": "CMakeHelloWorld.exe (Debug\\CMakeHelloWorld.exe)",
      "args": ["${cmake.remoteCopySources}"]
    }
  ]
}

また、構文 ${env.VARIABLE_NAME} を使用して、CMakeSettings.json で定義されている環境変数を launch.vs.json で使用することもできます。 Visual Studio 2019 バージョン 16.4 以降では、CMakeSettings.json で指定した環境を使用して、デバッグターゲットが自動的に起動されます。環境変数は、null に設定することで、設定解除できます。

Launch.vs.json の参照

launch.vs.json には、あらゆるデバッグシナリオをサポートするためのプロパティが多数あります。次のプロパティは、リモートとローカルの両方において、すべてのデバッグ構成に共通です。

projectTarget: プロジェクトのビルド時に呼び出す CMake ターゲットを指定します。 [デバッグ] メニューまたはターゲットビューから launch.vs.json にアクセスすると、Visual Studio によって、このプロパティが自動的に設定されます。この値は、[スタートアップアイテム] ドロップダウンに表示されている既存のデバッグターゲットの名前と一致する必要があります。

env: 構文を使用して追加する追加の環境変数:

"env": {
      "DEBUG_LOGGING_LEVEL": "trace;info",
      "ENABLE_TRACING": "true"
    }

args: デバッグするためにプログラムに渡されるコマンドライン引数。

リモートプロジェクトおよび WSL 用の Launch.vs.json の参照

Visual Studio 2019 バージョン 16.6 では、リモートシステムおよび WSL でのデバッグを簡略化するために、新しいデバッグ構成の type: cppgdb が追加されました。古いデバッグ構成の type: cppdbg は引き続きサポートされます。

構成の種類 `cppgdb`

name: [スタートアップアイテム] ドロップダウンで構成を識別するためのフレンドリ名。
project: プロジェクトファイルへの相対パスを指定します。通常、CMake プロジェクトをデバッグするときに、このパスを変更する必要はありません。
projectTarget: プロジェクトのビルド時に呼び出す CMake ターゲットを指定します。 [デバッグ] メニューまたはターゲットビューから launch.vs.json にアクセスすると、Visual Studio によって、このプロパティが自動的に設定されます。このターゲット値は、[スタートアップアイテム] ドロップダウンに表示されている既存のデバッグターゲットの名前と一致している必要があります。
debuggerConfiguration: 使用するデバッグの既定値のセットを示します。 Visual Studio 2019 バージョン 16.6 では、有効なオプションは gdbのみです。 Visual Studio 2019 バージョン 16.7 以降は gdbserver もサポートしています。
args: 起動時にデバッグ中のプログラムに渡されるコマンドライン引数。
env: デバッグ対象のプログラムに渡される追加の環境変数。たとえば、{"DISPLAY": "0.0"} のようにします。
processID: アタッチする Linux プロセス ID。リモートプロセスにアタッチする場合にのみ使用されます。詳細については、「GDB を使用したプロセスへのアタッチのトラブルシューティング」を参照してください。

`gdb` 構成の追加オプション

program:既定値は "${debugInfo.fullTargetPath}" です。デバッグするアプリケーションへの UNIX パス。ビルドまたは配置場所のターゲット実行可能ファイルと異なる場合にのみ必須です。
remoteMachineName:既定値は "${debugInfo.remoteMachineName}" です。デバッグするプログラムをホストするリモートシステムの名前。ビルドシステムと異なる場合にのみ必須です。接続マネージャーに既存のエントリがなければなりません。 Ctrl + Space キーを押して、すべての既存のリモート接続を一覧表示します。
cwd:既定値は "${debugInfo.defaultWorkingDirectory}" です。 program が実行されるリモートシステム上のディレクトリへの UNIX パス。このディレクトリが存在している必要があります。
gdbpath:既定値は /usr/bin/gdb です。デバッグに使用される gdb への完全な UNIX パス。 gdb のカスタムバージョンを使用する場合にのみ必須です。
preDebugCommand: gdbを呼び出す直前に実行する Linux コマンド。このコマンドが完了するまで gdb は開始されません。このオプションを使用すると、gdb の実行前にスクリプトを実行できます。

`gdbserver` 構成で使用できるその他のオプション (16.7 以降)

program:既定値は "${debugInfo.fullTargetPath}" です。デバッグするアプリケーションへの UNIX パス。ビルドまたは配置場所のターゲット実行可能ファイルと異なる場合にのみ必須です。

ヒント

配置は、ローカルのクロスコンパイルシナリオではまだサポートされていません。 Windows でクロスコンパイルを行う場合 (たとえば、Windows でクロスコンパイラを使用して Linux ARM 実行可能ファイルをビルドする場合)、デバッグする前に、リモート ARM コンピューターで program で指定された場所にバイナリを手動でコピーする必要があります。
remoteMachineName:既定値は "${debugInfo.remoteMachineName}" です。デバッグするプログラムをホストするリモートシステムの名前。ビルドシステムと異なる場合にのみ必須です。接続マネージャーに既存のエントリがなければなりません。 Ctrl + Space キーを押して、すべての既存のリモート接続を一覧表示します。
cwd:既定値は "${debugInfo.defaultWorkingDirectory}" です。 program が実行されるリモートシステム上のディレクトリへの完全な UNIX パス。このディレクトリが存在している必要があります。
gdbPath:既定値は ${debugInfo.vsInstalledGdb} です。デバッグに使用される gdb の完全な Windows パス。既定値は、C および C++ ワークロードを使用する Linux 開発でインストールされる gdb です。
gdbserverPath:既定値は usr/bin/gdbserver です。デバッグに使用される gdbserver への完全な UNIX パス。
preDebugCommand: gdbserverを開始する直前に実行する Linux コマンド。このコマンドが完了するまで gdbserver は開始されません。

配置オプション

次のオプションを使用して、リモートデバッグマシンからビルドマシン (CMakeSettings.json で定義) を分離します。

remoteMachineName: リモートデバッグマシン。ビルドマシンと異なる場合にのみ必須です。接続マネージャーに既存のエントリがなければなりません。 Ctrl + Space キーを押して、すべての既存のリモート接続を一覧表示します。
disableDeploy:既定値は false です。ビルドとデバッグの分離が無効になっているかどうかを示します。このオプションが false の場合、2 つの異なるマシンでビルドとデバッグを実行できます。
deployDirectory: 実行可能ファイルがコピーされる remoteMachineName 上のディレクトリへの完全な Unix パス。
deploy: デプロイの詳細設定の配列。配置プロセスをより細かく制御する場合にのみ、これらの設定を構成する必要があります。既定では、リモートデバッグマシンには、デバッグプロセスに必要なファイルのみが配置されます。
- sourceMachine: ファイルまたはディレクトリのコピー元のコンピューター。 Ctrl + Space キーを押して、接続マネージャーに格納されているすべてのリモート接続を一覧表示します。 WSL でネイティブにビルドする場合、このオプションは無視されます。
- targetMachine: ファイルまたはディレクトリのコピー先のマシン。 Ctrl + Space キーを押して、接続マネージャーに格納されているすべてのリモート接続を一覧表示します。
- sourcePath: sourceMachine上のファイルまたはディレクトリの場所。
- targetPath: targetMachine上のファイルまたはディレクトリの場所。
- deploymentType: デプロイの種類の説明。 LocalRemote と RemoteRemote がサポートされています。 LocalRemote は、ローカルシステムから、launch.vs.json の remoteMachineName で指定されたリモートシステムへのコピーを意味します。 RemoteRemote は、CMakeSettings.json に指定されたリモートビルドシステムから、launch.vs.json に指定された別のリモートシステムへのコピーを意味します。
- executable: デプロイされたファイルが実行可能ファイルかどうかを示します。

カスタムの `gdb` コマンドを実行する

Visual Studio では、基になるデバッガーを直接操作するカスタムの gdb コマンドの実行がサポートされています。詳細については、「カスタムの gdb lldb コマンドの実行」を参照してください。

ログの有効化

gdb に送信されるコマンド、gdb から返される出力、各コマンドの所要時間を確認するには、MIEngine ログを有効にします。詳細情報

構成の種類 `cppdbg`

構成の種類 cppdbg を使用してリモートシステムまたは WSL でデバッグする場合は、次のオプションを使用できます。 Visual Studio 2019 バージョン 16.6 以降では、構成の種類 cppgdb をお勧めします。

name: [スタートアップアイテム] ドロップダウンで構成を識別するためのフレンドリ名。
project: プロジェクトファイルへの相対パスを指定します。通常、CMake プロジェクトをデバッグするときに、この値を変更する必要はありません。
projectTarget: プロジェクトのビルド時に呼び出す CMake ターゲットを指定します。 [デバッグ] メニューまたはターゲットビューから launch.vs.json にアクセスすると、Visual Studio によって、このプロパティが自動的に設定されます。この値は、[スタートアップアイテム] ドロップダウンに表示されている既存のデバッグターゲットの名前と一致する必要があります。
args: 起動時にデバッグ中のプログラムに渡されるコマンドライン引数。
processID: アタッチする Linux プロセス ID。リモートプロセスにアタッチする場合にのみ使用されます。詳細については、「GDB を使用したプロセスへのアタッチのトラブルシューティング」を参照してください。
program:既定値は "${debugInfo.fullTargetPath}" です。デバッグするアプリケーションへの UNIX パス。ビルドまたは配置場所のターゲット実行可能ファイルと異なる場合にのみ必須です。
remoteMachineName:既定値は "${debugInfo.remoteMachineName}" です。デバッグするプログラムをホストするリモートシステムの名前。ビルドシステムと異なる場合にのみ必須です。接続マネージャーに既存のエントリがなければなりません。 Ctrl + Space キーを押して、すべての既存のリモート接続を一覧表示します。
cwd:既定値は "${debugInfo.defaultWorkingDirectory}" です。 program が実行されるリモートシステム上のディレクトリへの完全な UNIX パス。このディレクトリが存在している必要があります。

environment: デバッグ対象のプログラムに渡される追加の環境変数。たとえば、にします。

  "environment": [
      {
        "name": "ENV1",
        "value": "envvalue1"
      },
      {
        "name": "ENV2",
        "value": "envvalue2"
      }
    ]

pipeArgs: 接続を構成するためにパイププログラムに渡されるコマンドライン引数の配列。パイププログラムは、Visual Studio と gdb の間で標準の入出力をリレーするために使用されます。この配列の大部分は、CMake プロジェクトをデバッグするときにカスタマイズする必要はありません。リモートシステムでgdb を起動する ${debuggerCommand} コマンドは例外です。これは、次の操作を行うように変更できます。
- 環境変数 DISPLAY の値を Linux システムにエクスポートします。次の例では、この値は :1 です。
```
"pipeArgs": [
    "/s",
    "${debugInfo.remoteMachineId}",
    "/p",
    "${debugInfo.parentProcessId}",
    "/c",
    "export DISPLAY=:1;${debuggerCommand}",
    "--tty=${debugInfo.tty}"
  ],
```
- gdb の実行前にスクリプトを実行します。スクリプトに実行権限が設定されていることを確認してください。
```
"pipeArgs": [
    "/s",
    "${debugInfo.remoteMachineId}",
    "/p",
    "${debugInfo.parentProcessId}",
    "/c",
    "/path/to/script.sh;${debuggerCommand}",
    "--tty=${debugInfo.tty}"
  ],
```
stopOnEntry: プロセスが起動されるとすぐに中断するかどうかを指定するブール値。既定値は false です。
visualizerFile: このプロセスをデバッグするときに使用する .natvis ファイル。このオプションは gdb 再フォーマットと互換性がありません。このプロパティを設定する場合は showDisplayString も設定します。
showDisplayString: visualizerFile が指定されたときに表示文字列を有効にするブール値。このオプションを true に設定すると、デバッグ中にパフォーマンスが低下する可能性があります。
setupCommands: 基になるデバッガーを設定するために実行する 1 つ以上の gdb コマンド。
miDebuggerPath: gdbへの完全なパス。指定しない場合、Visual Studio では、デバッガーのパスを最初に検索します。
最後に、構成の種類 cppgdb に対して定義されたすべての配置オプションは、構成の種類 cppdbg でも使用できます。

`gdbserver` を使用してデバッグする

gdbserver を使用してデバッグするように、cppdbg 構成を構成できます。詳細情報とサンプルの起動構成については、Microsoft C++ チームのブログ「gdbserver を使用した Linux CMake プロジェクトのデバッグ」を参照してください。

次の方法で共有

CMake デバッグセッションを構成する

デバッガー設定をカスタマイズする

CMakeSettings.json のキーを参照する

Launch.vs.json の参照

リモートプロジェクトおよび WSL 用の Launch.vs.json の参照

構成の種類 `cppgdb`

`gdb` 構成の追加オプション

`gdbserver` 構成で使用できるその他のオプション (16.7 以降)

配置オプション

カスタムの `gdb` コマンドを実行する

ログの有効化

構成の種類 `cppdbg`

`gdbserver` を使用してデバッグする

関連項目

フィードバック

その他のリソース

次の方法で共有

CMake デバッグ セッションを構成する

デバッガー設定をカスタマイズする

CMakeSettings.json のキーを参照する

Launch.vs.json の参照

リモート プロジェクトおよび WSL 用の Launch.vs.json の参照

構成の種類 cppgdb

gdb 構成の追加オプション

gdbserver 構成で使用できるその他のオプション (16.7 以降)

配置オプション

カスタムの gdb コマンドを実行する

ログの有効化

構成の種類 cppdbg

gdbserver を使用してデバッグする

関連項目

フィードバック

その他のリソース

CMake デバッグセッションを構成する

リモートプロジェクトおよび WSL 用の Launch.vs.json の参照

構成の種類 `cppgdb`

`gdb` 構成の追加オプション

`gdbserver` 構成で使用できるその他のオプション (16.7 以降)

カスタムの `gdb` コマンドを実行する

構成の種類 `cppdbg`

`gdbserver` を使用してデバッグする