Freigeben über

Konfigurieren von CMake-Debugsitzungen

  • Artikel

Die native Unterstützung für CMake ist in Visual Studio 2017 und höher verfügbar. Um die Dokumentation für diese Versionen anzuzeigen, legen Sie das Auswahlsteuerelement Version in Visual Studio für diesen Artikel auf Visual Studio 2017 oder höher fest. Es befindet sich am Anfang des Inhaltsverzeichnisses auf dieser Seite.

Alle ausführbaren CMake-Ziele werden in der Dropdownliste Startelement in der Symbolleiste angezeigt. Wählen Sie eine Version aus, um eine Debugsitzung und somit den Debugger zu starten.

Screenshot der Dropdownliste

Sie können eine Debugsitzung auch über den Projektmappen-Explorer starten. Wechseln Sie zunächst zur Ansicht CMake-Zielansicht im Fenster Projektmappen-Explorer.

Screenshot des Menüs

Klicken Sie dann mit der rechten Maustaste auf eine ausführbare Datei und dann auf Debuggen. Mit diesem Befehl wird das Debuggen des ausgewählten Ziels basierend auf der aktiven Konfiguration automatisch gestartet.

Screenshot des Menüs

Ab Visual Studio 2022, Version 17.6, können Sie auch eine Debugsitzung in Ihrer CMakeLists.txt Datei starten. Legen Sie dazu einfach einen Haltepunkt in Ihrer CMakeLists.txt-Datei fest, und führen Sie "Projekt mit CMake Debugger konfigurieren" aus der Project-Dropdownliste aus.

Screenshot der Dropdownliste

Anpassen von Debuggereinstellungen

Sie können die Debuggereinstellungen für alle ausführbaren CMake-Ziele im Projekt anpassen. Sie befinden sich in einer Konfigurationsdatei namens launch.vs.json, die sich in einem .vs-Ordner im Projektstamm befindet. Eine Startkonfigurationsdatei ist in den meisten Debugszenarios nützlich, da Sie die Details zum Debuggen konfigurieren und speichern können. Es gibt drei Einstiegspunkte für diese Datei:

  • Debugmenü: Wählen Sie die Debug- > und Starteinstellungen für ${activeDebugTarget} aus dem Hauptmenü aus, um die für Ihr aktives Debugziel spezifische Debugkonfiguration anzupassen. Wenn Sie kein Debugziel ausgewählt haben, ist diese Option ausgegraut.

Screenshot des Menübefehls „Debuggen“: Debug- und Starteinstellungen für das Projekt.

  • Zielansicht: Navigieren Sie in Projektmappen-Explorer zur Zielansicht. Klicken Sie dann mit der rechten Maustaste auf ein Debugziel und dann auf Add Debug Configuration (Debugkonfiguration hinzufügen), um die für das Debugziel spezifische Debugkonfiguration anzupassen.

Screenshot des Befehls zum Hinzufügen der Debugkonfiguration im Kontextmenü für das Ziel.

  • Stamm-CMakeLists.txt: Klicken Sie mit der rechten Maustaste auf eine Stamm-CMakeLists.txt, und wählen Sie "Debugkonfiguration hinzufügen" aus, um das Dialogfeld "Debugger auswählen" zu öffnen. Mit dem Dialogfeld können Sie jeden beliebigen Typ der Debugkonfiguration hinzufügen. Sie müssen das CMake-Ziel jedoch manuell angeben, um dieses über die projectTarget-Eigenschaft aufzurufen.

Screenshot: Dialogfeld „Debugger auswählen“.

Sie können die launch.vs.json-Datei bearbeiten, um Debugkonfigurationen für eine beliebige Anzahl von CMake-Zielen zu erstellen. Wenn Sie die Datei speichern, erstellt Visual Studio im Dropdownmenü Startelement einen Eintrag für jede neue Konfiguration.

Verweisschlüssel in CMakeSettings.json

Stellen Sie in der launch.vs.json-Datei cmake. voran, um in einer CMakeSettings.json-Datei auf einen beliebigen Schlüssel zu verweisen. In folgendem Beispiel wird eine einfache launch.vs.json-Datei dargestellt, die den Wert des Schlüssels remoteCopySources aus der Datei CMakeSettings.json für die derzeit ausgewählte Konfiguration abruft:

{
  "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}"]
    }
  ]
}

Die in der CMakeSettings.json-Datei definierten Umgebungsvariablen können mithilfe der Syntax ${env.VARIABLE_NAME} auch in „launch.vs.json“ verwendet werden. In Visual Studio 2019, Version 16.4 und höher werden Debugziele mithilfe der in der CMakeSettings.json-Datei angegebenen Umgebung automatisch gestartet. Sie können eine Umgebungsvariable zurücksetzen, indem Sie sie auf Null festlegen.

Launch.vs.json-Verweis

Es gibt viele launch.vs.json-Eigenschaften, die alle Debugszenarios unterstützen. Die folgenden Eigenschaften gelten sowohl für alle lokalen als auch für Remotedebugkonfigurationen:

  • projectTarget: Gibt das CMake-Ziel an, das beim Erstellen des Projekts aufgerufen werden soll. Visual Studio füllt diese Eigenschaft automatisch auf, wenn Sie launch.vs.json im Menü „Debuggen“ oder in der Targets View (Zielansicht) eingeben. Dieser Wert muss mit dem Namen eines vorhandenen Debugziels übereinstimmen, das im Dropdownmenü Startelement aufgeführt wird.

  • env: Zusätzliche Umgebungsvariablen, die mithilfe der Syntax hinzugefügt werden sollen:

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

  • args: Befehlszeilenargumente, die an das zu debuggende Programm übergeben werden.

Launch.vs.json-Verweis für Remoteprojekte und WSL

In Visual 2019, Version 16.6 haben wir eine neue Debugkonfiguration von type: cppgdb hinzugefügt, um das Debuggen auf Remotesystemen und WSL zu vereinfachen. Alte Debugkonfigurationen von type: cppdbg werden weiterhin unterstützt.

Konfigurationstyp cppgdb

  • name: Ein Anzeigename zum Identifizieren der Konfiguration im Dropdownmenü "Startelement ".
  • project: Gibt den relativen Pfad zur Projektdatei an. Normalerweise müssen Sie diesen Pfad beim Debuggen eines CMake-Projekts nicht ändern.
  • projectTarget: Gibt das CMake-Ziel an, das beim Erstellen des Projekts aufgerufen werden soll. Visual Studio füllt diese Eigenschaft automatisch auf, wenn Sie launch.vs.json im Menü „Debuggen“ oder in der Targets View (Zielansicht) eingeben. Dieser Zielwert muss mit dem Namen eines vorhandenen Debugziels übereinstimmen, das im Dropdownmenü Startelement aufgeführt wird.
  • debuggerConfiguration: Gibt an, welche Gruppe von Debugstandardwerten verwendet werden soll. In Visual Studio 2019, Version 16.6 ist gdb die einzige gültige Option. Visual Studio 2019, Version 16.7 oder höher, bietet ebenfalls Unterstützung für gdbserver.
  • args: Befehlszeilenargumente, die beim Start an das zu debuggende Programm übergeben werden.
  • env: Zusätzliche Umgebungsvariablen, die an das zu debuggende Programm übergeben werden. Beispiel: {"DISPLAY": "0.0"}.
  • processID: Linux-Prozess-ID, an die angefügt werden soll. Diese wird nur beim Anhängen an einen Remoteprozess verwendet. Weitere Informationen finden Sie unter Problembehandlung beim Anhängen an Prozesse mithilfe von gdb.

Zusätzliche Optionen für die gdb-Konfiguration

  • program: Wird standardmäßig auf "${debugInfo.fullTargetPath}" festgelegt. Dies ist der UNIX-Pfad zu der zu debuggenden Anwendung. Dieser ist nur erforderlich, wenn dieser von dem der ausführbaren Zieldatei im Build- oder Bereitstellungsspeicherort abweicht.
  • remoteMachineName: Wird standardmäßig auf "${debugInfo.remoteMachineName}" festgelegt. Dies ist der Name des Remotesystems, das das zu debuggende Programm hostet. Dieser ist nur erforderlich, wenn er von dem des Buildsystems abweicht. Im Verbindungs-Manager muss ein Eintrag vorhanden sein. Drücken Sie STRG+LEERTASTE, um eine Liste aller vorhandenen Remoteverbindungen anzuzeigen.
  • cwd: Wird standardmäßig auf "${debugInfo.defaultWorkingDirectory}" festgelegt. Dies ist der UNIX-Pfad zum Verzeichnis auf dem Remotesystem, auf dem program ausgeführt wird. Das Verzeichnis muss vorhanden sein.
  • gdbpath: Wird standardmäßig auf /usr/bin/gdb festgelegt. Dies ist der vollständige UNIX-Pfad zu dem zum Debuggen verwendeten gdb-Befehl. Dieser ist nur erforderlich, wenn eine benutzerdefinierte Version von gdb verwendet wird.
  • preDebugCommand: Ein Linux-Befehl, der unmittelbar vor dem Aufrufen gdbausgeführt werden soll. gdb wird nicht gestartet, bis der Befehl abgeschlossen ist. Sie können die Option verwenden, um ein Skript vor der Ausführung von gdb auszuführen.

Mit der gdbserver-Konfiguration (16.7 oder höher) sind weitere Optionen zulässig.

  • program: Wird standardmäßig auf "${debugInfo.fullTargetPath}" festgelegt. Dies ist der UNIX-Pfad zu der zu debuggenden Anwendung. Dieser ist nur erforderlich, wenn dieser von dem der ausführbaren Zieldatei im Build- oder Bereitstellungsspeicherort abweicht.

    Tipp

    Für lokale Kreuzkompilierungsszenarios wird die Bereitstellung noch nicht unterstützt. Wenn Sie unter Windows eine Kreuzkompilierung durchführen (z. B. wenn Sie mit einem Kreuzcompiler unter Windows eine ausführbare ARM-Datei für Linux erstellen), müssen Sie die Binärdatei vor dem Debuggen manuell an den bei program angegebenen Speicherort auf dem ARM-Remotecomputer kopieren.

  • remoteMachineName: Wird standardmäßig auf "${debugInfo.remoteMachineName}" festgelegt. Dies ist der Name des Remotesystems, das das zu debuggende Programm hostet. Dieser ist nur erforderlich, wenn er von dem des Buildsystems abweicht. Im Verbindungs-Manager muss ein Eintrag vorhanden sein. Drücken Sie STRG+LEERTASTE, um eine Liste aller vorhandenen Remoteverbindungen anzuzeigen.

  • cwd: Wird standardmäßig auf "${debugInfo.defaultWorkingDirectory}" festgelegt. Dies ist der vollständige UNIX-Pfad zum Verzeichnis auf dem Remotesystem, auf dem program ausgeführt wird. Das Verzeichnis muss vorhanden sein.

  • gdbPath: Wird standardmäßig auf ${debugInfo.vsInstalledGdb} festgelegt. Dies ist der vollständige Windows-Pfad zum gdb-Befehl, der für das Debuggen verwendet wird. Entspricht standardmäßig gdb (wird mit der Linux-Entwicklung mit der C/C++-Workload installiert).

  • gdbserverPath: Wird standardmäßig auf usr/bin/gdbserver festgelegt. Dies ist der vollständige UNIX-Pfad zu dem zum Debuggen verwendeten gdbserver-Befehl.

  • preDebugCommand: Ein Linux-Befehl, der unmittelbar vor dem Start gdbserverausgeführt werden soll. gdbserver wird nicht gestartet, bis der Befehl abgeschlossen ist.

Bereitstellungsoptionen

Verwenden Sie die folgenden Optionen, um den (in der CMakeSettings.json-Datei definierten) Buildcomputer vom Remotedebugcomputer zu trennen.

  • remoteMachineName: Remotedebugcomputer. Dieser ist nur erforderlich, wenn er von dem des Buildcomputers abweicht. Im Verbindungs-Manager muss ein Eintrag vorhanden sein. Drücken Sie STRG+LEERTASTE, um eine Liste aller vorhandenen Remoteverbindungen anzuzeigen.
  • disableDeploy: Wird standardmäßig auf false festgelegt. Hiermit wird angegeben, ob die Build- bzw. Debugtrennung deaktiviert ist. Im Falle von false ermöglicht diese Option das Durchführen von Build- und Debugvorgängen auf zwei separaten Computern.
  • deployDirectory: Vollständiger Unix-Pfad zum Verzeichnis, in remoteMachineName das die ausführbare Datei kopiert wird.
  • deploy: Ein Array erweiterter Bereitstellungseinstellungen. Sie müssen diese Einstellungen nur konfigurieren, wenn Sie genauere Kontrolle über den Bereitstellungsprozess wünschen. Standardmäßig werden nur die Dateien, die für den zu debuggenden Prozess erforderlich sind, auf dem Remotedebugcomputer bereitgestellt.
    • sourceMachine: Der Computer, von dem die Datei oder das Verzeichnis kopiert wird. Drücken Sie STRG+LEERTASTE, um eine Liste aller im Verbindungs-Manager gespeicherten Remoteverbindungen anzuzeigen. Wenn Sie nativ auf WSL aufbauen, wird diese Option ignoriert.
    • targetMachine: Der Computer, auf den die Datei oder das Verzeichnis kopiert wird. Drücken Sie STRG+LEERTASTE, um eine Liste aller im Verbindungs-Manager gespeicherten Remoteverbindungen anzuzeigen.
    • sourcePath: Der Datei- oder Verzeichnisspeicherort auf sourceMachine.
    • targetPath: Der Datei- oder Verzeichnisspeicherort auf targetMachine.
    • deploymentType: Eine Beschreibung des Bereitstellungstyps. LocalRemote und RemoteRemote werden unterstützt. LocalRemote bedeutet, dass von dem lokalen Dateisystem auf das Remotesystem kopiert wird, das durch remoteMachineName in der launch.vs.json-Datei angegeben wird. RemoteRemote bedeutet, dass von dem in der CMakeSettings.json-Datei angegebenen Remotebuildsystem auf das andere in der launch.vs.json-Datei angegebene Remotesystem kopiert wird.
    • executable: Gibt an, ob die bereitgestellte Datei eine ausführbare Datei ist.

Ausführen benutzerdefinierter gdb-Befehle

Visual Studio unterstützt das Ausführen von benutzerdefinierten gdb-Befehlen, um direkt mit dem zugrunde liegenden Debugger zu interagieren. Weitere Informationen finden Sie unter Ausführen benutzerdefinierter -lldb-Befehlegdb.

Aktivieren der Protokollierung

Aktivieren Sie die MIEngine-Protokollierung, um anzuzeigen, welche Befehle an gdb gesendet werden, welche Ausgabe gdb zurückgibt und wie lange die einzelnen Befehle dauern. Weitere Informationen

Konfigurationstyp cppdbg

Die folgenden Optionen können beim Debuggen auf einem Remotesystem oder WSL mit dem Konfigurationstyp cppdbg verwendet werden. In Visual Studio 2019, Version 16.6 oder höher wird der Konfigurationstyp cppgdb empfohlen.

  • name: Ein Anzeigename zum Identifizieren der Konfiguration im Dropdownmenü "Startelement ".

  • project: Gibt den relativen Pfad zur Projektdatei an. Normalerweise müssen Sie diesen Wert beim Debuggen eines CMake-Projekts nicht ändern.

  • projectTarget: Gibt das CMake-Ziel an, das beim Erstellen des Projekts aufgerufen werden soll. Visual Studio füllt diese Eigenschaft automatisch auf, wenn Sie launch.vs.json im Menü „Debuggen“ oder in der Targets View (Zielansicht) eingeben. Dieser Wert muss mit dem Namen eines vorhandenen Debugziels übereinstimmen, das im Dropdownmenü Startelement aufgeführt wird.

  • args: Befehlszeilenargumente, die beim Start an das zu debuggende Programm übergeben werden.

  • processID: Linux-Prozess-ID, an die angefügt werden soll. Diese wird nur beim Anhängen an einen Remoteprozess verwendet. Weitere Informationen finden Sie unter Problembehandlung beim Anhängen an Prozesse mithilfe von gdb.

  • program: Wird standardmäßig auf "${debugInfo.fullTargetPath}" festgelegt. Dies ist der UNIX-Pfad zu der zu debuggenden Anwendung. Dieser ist nur erforderlich, wenn dieser von dem der ausführbaren Zieldatei im Build- oder Bereitstellungsspeicherort abweicht.

  • remoteMachineName: Wird standardmäßig auf "${debugInfo.remoteMachineName}" festgelegt. Dies ist der Name des Remotesystems, das das zu debuggende Programm hostet. Dieser ist nur erforderlich, wenn er von dem des Buildsystems abweicht. Im Verbindungs-Manager muss ein Eintrag vorhanden sein. Drücken Sie STRG+LEERTASTE, um eine Liste aller vorhandenen Remoteverbindungen anzuzeigen.

  • cwd: Wird standardmäßig auf "${debugInfo.defaultWorkingDirectory}" festgelegt. Dies ist der vollständige UNIX-Pfad zum Verzeichnis auf dem Remotesystem, auf dem program ausgeführt wird. Das Verzeichnis muss vorhanden sein.

  • environment: Zusätzliche Umgebungsvariablen, die an das zu debuggende Programm übergeben werden. Beispiel: 

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

  • pipeArgs: Ein Array von Befehlszeilenargumenten, die an das Pipeprogramm übergeben werden, um die Verbindung zu konfigurieren. Das Pipeprogramm wird verwendet, um Standardeingaben und -ausgaben zwischen Visual Studio und gdb weiterzuleiten. Beim Debuggen von CMake-Projekten muss ein Großteil dieses Arrays nicht angepasst werden. ${debuggerCommand} bildet die Ausnahme, da hiermit gdb auf dem Remotesystem gestartet wird. Dies kann wie folgt geändert werden:

    • Exportieren Sie den Wert der Umgebungsvariablen „DISPLAY“ auf Ihrem Linux-System. Im folgenden Beispiel lautet dieser Wert :1.

      "pipeArgs": [
    "/s",
    "${debugInfo.remoteMachineId}",
    "/p",
    "${debugInfo.parentProcessId}",
    "/c",
    "export DISPLAY=:1;${debuggerCommand}",
    "--tty=${debugInfo.tty}"
  ],

    • Führen Sie vor der Ausführung von gdb ein Skript aus. Stellen Sie sicher, dass die Ausführungsberechtigungen für Ihr Skript festgelegt sind.

      "pipeArgs": [
    "/s",
    "${debugInfo.remoteMachineId}",
    "/p",
    "${debugInfo.parentProcessId}",
    "/c",
    "/path/to/script.sh;${debuggerCommand}",
    "--tty=${debugInfo.tty}"
  ],

  • stopOnEntry: Ein boolescher Wert, der angibt, ob der Vorgang unterbrochen werden soll, sobald der Prozess gestartet wird. Die Standardeinstellung ist „false“.

  • visualizerFile: Eine NATVIS-Datei, die beim Debuggen dieses Prozesses verwendet werden soll. Diese Option ist nicht mit der automatischen Strukturierung und Einrückung von gdb kompatibel. Legen Sie auch showDisplayString fest, wenn Sie diese Eigenschaft festlegen.

  • showDisplayString: Ein boolescher Wert, der die Anzeigezeichenfolge aktiviert, wenn ein visualizerFile Wert angegeben wird. Wenn diese Option auf true festgelegt wird, kann die Leistung beim Debuggen verlangsamt werden.

  • setupCommands: Ein oder mehrere gdb auszuführende Befehle, um den zugrunde liegenden Debugger einzurichten.

  • miDebuggerPath: Der vollständige Pfad zu gdb. Wenn dieser nicht angegeben ist, sucht Visual Studio zuerst nach dem Pfad für den Debugger.

  • Schließlich können auch alle Bereitstellungsoptionen, die für den Konfigurationstyp cppgdb definiert sind, vom Konfigurationstyp cppdbg verwendet werden.

Debuggen mithilfe von gdbserver

Sie können die cppdbg-Konfiguration zum Debuggen mithilfe von gdbserver konfigurieren. Weitere Details und ein Beispiel für eine Startkonfiguration finden Sie im Blogbeitrag Debuggen von Linux-CMake-Projekten mithilfe vongdbserver des Microsoft C++-Teams.