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

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

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

Screenshot of the CMake startup items dropdown.

ドロップダウンには、選択するデバッグ ターゲットの一覧が表示されます。 選択した項目が再生ボタンとして表示され、その後に実行する選択したデバッグ ターゲットの名前が表示されます。 この例では、選択したデバッグ ターゲットは Hello World .exe です。

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

Screenshot of the CMake Targets View menu.

ソリューション エクスプローラーが表示されます。 フォルダー ビューの項目を右クリックすると、メニューが開き、開く、開く、比較するなどのオプションが表示されます。 [ターゲット ビューに切り替え] メニュー項目が強調表示されています。

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

Screenshot of the CMake Targets View debug option menu.

CMake ターゲット ビューでターゲットを右クリックすると、メニューが開き、スタートアップ項目として設定、ビルド、すべてクリーンアップなどのオプションが表示されます。 [デバッグ] メニュー オプションが強調表示されています。

Visual Studio 2022 バージョン 17.6 以降では、CMakeLists.txt ファイルでデバッグ セッションを開始することもできます。 これを行うには、CMakeLists.txt ファイルにブレークポイントを設定し、[プロジェクト] ドロップダウンから CMake デバッガーを使用してプロジェクトの構成を実行するだけです。

Screenshot of the CMake Debugger dropdown.

[プロジェクト] ドロップダウンが表示されます。 CMake デバッガーを使用してプロジェクトを構成するためのメニュー オプションが強調表示されています。

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

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

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

Screenshot of the Debug menu command Debug and launch settings for the project.

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

Screenshot of the Add Debug Configuration command on the shortcut menu for the target.

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

Screenshot of the Select a debugger dialog box.

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: 呼び出す直前に実行する gdbLinux コマンド。 このコマンドが完了するまで 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: デプロイの種類の説明。 LocalRemoteRemoteRemote がサポートされています。 LocalRemote は、ローカル システムから、launch.vs.jsonremoteMachineName で指定されたリモート システムへのコピーを意味します。 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: a が指定されたときに visualizerFile 表示文字列を有効にするブール値。 このオプションを true に設定すると、デバッグ中にパフォーマンスが低下する可能性があります。

  • setupCommands: 基になるデバッガーを設定するために実行する 1 つ以上 gdb のコマンド。

  • miDebuggerPath: への完全なパス gdb。 指定しない場合、Visual Studio では、デバッガーのパスを最初に検索します。

  • 最後に、構成の種類 cppgdb に対して定義されたすべての配置オプションは、構成の種類 cppdbg でも使用できます。

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

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