Konfigurowanie sesji debugowania narzędzia CMake

  • Artykuł

Natywna obsługa narzędzia CMake jest dostępna w programie Visual Studio 2017 lub nowszym. Aby zapoznać się z dokumentacją dla tych wersji, ustaw kontrolkę selektora wersji programu Visual Studio dla tego artykułu na program Visual Studio 2017 lub nowszy. Znajduje się on w górnej części spisu treści na tej stronie.

Wszystkie elementy docelowe narzędzia CMake wykonywalne są wyświetlane na liście rozwijanej Element startowy na pasku narzędzi. Wybierz jeden, aby rozpocząć sesję debugowania i uruchomić debuger.

Screenshot of the CMake startup items dropdown.

Możesz również uruchomić sesję debugowania z Eksplorator rozwiązań. Najpierw przejdź do widoku obiektów docelowych narzędzia CMake w oknie Eksplorator rozwiązań.

Screenshot of the CMake Targets View menu.

Następnie kliknij prawym przyciskiem myszy plik wykonywalny i wybierz polecenie Debuguj. To polecenie automatycznie uruchamia debugowanie wybranego obiektu docelowego na podstawie aktywnej konfiguracji.

Screenshot of the CMake Targets View debug option menu.

Począwszy od programu Visual Studio 2022 w wersji 17.6, możesz również rozpocząć sesję debugowania w pliku CMakeLists.txt. W tym celu wystarczy ustawić punkt przerwania w pliku CMakeLists.txt i uruchomić polecenie Configure Project with CMake Debugger (Konfigurowanie projektu za pomocą narzędzia CMake Debugger) z listy rozwijanej Project (Projekt).

Screenshot of the CMake Debugger dropdown.

Dostosowywanie ustawień debugera

Ustawienia debugera można dostosować dla dowolnego pliku wykonywalnego obiektu docelowego narzędzia CMake w projekcie. Znajdują się one w pliku konfiguracji o nazwie launch.vs.json znajdującym się w folderze w .vs katalogu głównym projektu. Plik konfiguracji uruchamiania jest przydatny w większości scenariuszy debugowania, ponieważ można skonfigurować i zapisać szczegóły konfiguracji debugowania. W tym pliku znajdują się trzy punkty wejścia:

  • Menu debugowania: wybierz pozycję Debuguj > debugowanie i uruchom Ustawienia dla elementu ${activeDebugTarget} z menu głównego, aby dostosować konfigurację debugowania specyficzną dla aktywnego celu debugowania. Jeśli nie masz wybranego miejsca docelowego debugowania, ta opcja jest wyszaryzowana.

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

  • Widok obiektów docelowych: przejdź do widoku obiektów docelowych w Eksplorator rozwiązań. Następnie kliknij prawym przyciskiem myszy element docelowy debugowania i wybierz polecenie Dodaj konfigurację debugowania, aby dostosować konfigurację debugowania specyficzną dla wybranego miejsca docelowego.

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

  • Główny plik CMakeLists.txt: kliknij prawym przyciskiem myszy główny plik CMakeLists.txt i wybierz polecenie Dodaj konfigurację debugowania, aby otworzyć okno dialogowe Wybieranie debugera . Okno dialogowe umożliwia dodanie dowolnego typu konfiguracji debugowania, ale należy ręcznie określić obiekt docelowy narzędzia CMake do wywołania za pośrednictwem projectTarget właściwości .

Screenshot of the Select a debugger dialog box.

Plik launch.vs.json można edytować, aby utworzyć konfiguracje debugowania dla dowolnej liczby obiektów docelowych narzędzia CMake. Po zapisaniu pliku program Visual Studio tworzy wpis dla każdej nowej konfiguracji na liście rozwijanej Element uruchamiania.

Klucze odwołań w pliku CMake Ustawienia.json

Aby odwołać się do dowolnego klucza w pliku CMake Ustawienia.json, wstaw cmake. go w pliku launch.vs.json. Poniższy przykład przedstawia prosty plik launch.vs.json, który pobiera wartość remoteCopySources klucza w pliku CMake Ustawienia.json dla aktualnie wybranej konfiguracji:

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

Zmienne środowiskowe zdefiniowane w pliku CMake Ustawienia.json mogą być również używane w pliku launch.vs.json przy użyciu składni ${env.VARIABLE_NAME}. W programie Visual Studio 2019 w wersji 16.4 lub nowszej obiekty docelowe debugowania są uruchamiane automatycznie przy użyciu środowiska określonego w pliku CMake Ustawienia.json. Możesz usunąć ustawienie zmiennej środowiskowej, ustawiając ją na wartość null.

Dokumentacja pliku Launch.vs.json

Istnieje wiele właściwości launch.vs.json do obsługi wszystkich scenariuszy debugowania. Następujące właściwości są wspólne dla wszystkich konfiguracji debugowania, zarówno zdalnych, jak i lokalnych:

  • projectTarget: określa element docelowy narzędzia CMake do wywołania podczas kompilowania projektu. Program Visual Studio automatycznie wypełnia tę właściwość, jeśli wprowadzisz plik launch.vs.json z menu debugowania lub widoku elementów docelowych. Ta wartość musi być zgodna z nazwą istniejącego obiektu docelowego debugowania wymienionego na liście rozwijanej Element startowy.

  • env: Dodatkowe zmienne środowiskowe do dodania przy użyciu składni:

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

  • args: Argumenty wiersza polecenia przekazane do programu do debugowania.

Dokumentacja pliku Launch.vs.json dla projektów zdalnych i programu WSL

W programie Visual Studio 2019 w wersji 16.6 dodaliśmy nową konfigurację type: cppgdb debugowania w celu uproszczenia debugowania w systemach zdalnych i WSL. Stare konfiguracje type: cppdbg debugowania programu są nadal obsługiwane.

Typ konfiguracji cppgdb

  • name: przyjazna nazwa identyfikującą konfigurację na liście rozwijanej Element startowy.
  • project: określa ścieżkę względną do pliku projektu. Zwykle nie trzeba zmieniać tej ścieżki podczas debugowania projektu CMake.
  • projectTarget: określa element docelowy narzędzia CMake do wywołania podczas kompilowania projektu. Program Visual Studio automatycznie wypełnia tę właściwość, jeśli wprowadzisz plik launch.vs.json z menu debugowania lub widoku elementów docelowych. Ta wartość docelowa musi być zgodna z nazwą istniejącego obiektu docelowego debugowania wymienionego na liście rozwijanej Element startowy.
  • debuggerConfiguration: wskazuje, który zestaw wartości domyślnych debugowania ma być używany. W programie Visual Studio 2019 w wersji 16.6 jedyną prawidłową opcją jest gdb. Program Visual Studio 2019 w wersji 16.7 lub nowszej obsługuje również program gdbserver.
  • args: Argumenty wiersza polecenia przekazane podczas uruchamiania do debugowanego programu.
  • env: Dodatkowe zmienne środowiskowe przekazywane do debugowanego programu. Na przykład {"DISPLAY": "0.0"}.
  • processID: Identyfikator procesu systemu Linux do dołączenia. Używane tylko podczas dołączania do procesu zdalnego. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z dołączaniem do procesów przy użyciu usługi GDB.

Dodatkowe opcje konfiguracji gdb

  • program: Wartość domyślna to "${debugInfo.fullTargetPath}". Ścieżka systemu Unix do aplikacji do debugowania. Wymagane tylko wtedy, gdy plik wykonywalny jest inny niż docelowy plik wykonywalny w lokalizacji kompilacji lub wdrożenia.
  • remoteMachineName: Wartość domyślna to "${debugInfo.remoteMachineName}". Nazwa systemu zdalnego, który hostuje program do debugowania. Wymagane tylko wtedy, gdy system kompilacji różni się od systemu kompilacji. Musi mieć istniejący wpis w menedżerze Połączenie ion. Naciśnij klawisze Ctrl+Spacja , aby wyświetlić listę wszystkich istniejących połączeń zdalnych.
  • cwd: Wartość domyślna to "${debugInfo.defaultWorkingDirectory}". Ścieżka systemu Unix do katalogu w systemie zdalnym, w którym program jest uruchamiany. Ten katalog musi istnieć.
  • gdbpath: Wartość domyślna to /usr/bin/gdb. Pełna ścieżka systemu Unix do używanego gdb do debugowania. Wymagane tylko w przypadku używania niestandardowej wersji programu gdb.
  • preDebugCommand: Polecenie systemu Linux uruchamiane bezpośrednio przed wywołaniem gdbpolecenia . gdb nie uruchamia się, dopóki polecenie nie zostanie ukończone. Możesz użyć opcji , aby uruchomić skrypt przed wykonaniem polecenia gdb.

Dodatkowe opcje dozwolone z konfiguracją gdbserver (16.7 lub nowsza)

  • program: Wartość domyślna to "${debugInfo.fullTargetPath}". Ścieżka systemu Unix do aplikacji do debugowania. Wymagane tylko wtedy, gdy plik wykonywalny jest inny niż docelowy plik wykonywalny w lokalizacji kompilacji lub wdrożenia.

    Napiwek

    Wdrażanie nie jest jeszcze obsługiwane w lokalnych scenariuszach kompilacji krzyżowej. Jeśli kompilujesz krzyżowo w systemie Windows (na przykład przy użyciu kompilatora krzyżowego w systemie Windows w celu skompilowania pliku wykonywalnego arm systemu Linux), musisz ręcznie skopiować plik binarny do lokalizacji określonej przez program na zdalnej maszynie arm przed debugowaniem.

  • remoteMachineName: Wartość domyślna to "${debugInfo.remoteMachineName}". Nazwa systemu zdalnego, który hostuje program do debugowania. Wymagane tylko wtedy, gdy system kompilacji różni się od systemu kompilacji. Musi mieć istniejący wpis w menedżerze Połączenie ion. Naciśnij klawisze Ctrl+Spacja , aby wyświetlić listę wszystkich istniejących połączeń zdalnych.

  • cwd: Wartość domyślna to "${debugInfo.defaultWorkingDirectory}". Pełna ścieżka systemu Unix do katalogu w systemie zdalnym, w którym program jest uruchamiany. Ten katalog musi istnieć.

  • gdbPath: Wartość domyślna to ${debugInfo.vsInstalledGdb}. Pełna ścieżka systemu Windows do używanego gdb do debugowania. gdb Domyślnie jest instalowany z programowaniem systemu Linux z obciążeniem C/C++.

  • gdbserverPath: Wartość domyślna to usr/bin/gdbserver. Pełna ścieżka systemu Unix do używanego gdbserver do debugowania.

  • preDebugCommand: Polecenie systemu Linux uruchamiane bezpośrednio przed uruchomieniem gdbserverpolecenia . gdbserver nie uruchamia się, dopóki polecenie nie zostanie ukończone.

Opcje wdrażania

Użyj następujących opcji, aby oddzielić maszynę kompilacji (zdefiniowaną w pliku CMake Ustawienia.json) od maszyny zdalnego debugowania.

  • remoteMachineName: Zdalna maszyna debugowania. Wymagane tylko wtedy, gdy maszyna kompilacji jest inna niż maszyna kompilacji. Musi mieć istniejący wpis w menedżerze Połączenie ion. Naciśnij klawisze Ctrl+Spacja , aby wyświetlić listę wszystkich istniejących połączeń zdalnych.
  • disableDeploy: Wartość domyślna to false. Wskazuje, czy separacja kompilacji/debugowania jest wyłączona. Gdy falseta opcja umożliwia kompilowanie i debugowanie na dwóch oddzielnych maszynach.
  • deployDirectory: pełna ścieżka systemu Unix do katalogu, do remoteMachineName którego plik wykonywalny zostanie skopiowany.
  • deploy: tablica zaawansowanych ustawień wdrażania. Te ustawienia należy skonfigurować tylko wtedy, gdy chcesz mieć bardziej szczegółową kontrolę nad procesem wdrażania. Domyślnie tylko pliki niezbędne do debugowania procesu są wdrażane na maszynie debugowania zdalnego.
    • sourceMachine: maszyna, z której jest kopiowany plik lub katalog. Naciśnij klawisze Ctrl+Spacja, aby wyświetlić listę wszystkich połączeń zdalnych przechowywanych w menedżerze Połączenie ion. Podczas tworzenia natywnie w programie WSL ta opcja jest ignorowana.
    • targetMachine: maszyna, do której jest kopiowany plik lub katalog. Naciśnij klawisze Ctrl+Spacja, aby wyświetlić listę wszystkich połączeń zdalnych przechowywanych w menedżerze Połączenie ion.
    • sourcePath: lokalizacja pliku lub katalogu w lokalizacji .sourceMachine
    • targetPath: lokalizacja pliku lub katalogu w lokalizacji .targetMachine
    • deploymentType: opis typu wdrożenia. LocalRemote i RemoteRemote są obsługiwane. LocalRemote oznacza kopiowanie z lokalnego systemu plików do systemu zdalnego określonego przez remoteMachineName w pliku launch.vs.json. RemoteRemoteoznacza kopiowanie z zdalnego systemu kompilacji określonego w pliku CMake Ustawienia.json do innego systemu zdalnego określonego w pliku launch.vs.json.
    • executable: wskazuje, czy wdrożony plik jest plikiem wykonywalnym.

Wykonywanie poleceń niestandardowych gdb

Program Visual Studio obsługuje wykonywanie poleceń niestandardowych gdb w celu bezpośredniej interakcji z bazowym debugerem. Aby uzyskać więcej informacji, zobacz Wykonywanie niestandardowych gdbpoleceń lldb.

Włącz rejestrowanie

Włącz rejestrowanie MIEngine, aby zobaczyć, jakie polecenia są wysyłane do gdb, jakie dane wyjściowe gdb są zwracane i jak długo trwa każde polecenie. Dowiedz się więcej

Typ konfiguracji cppdbg

Poniższe opcje można użyć podczas debugowania w systemie zdalnym lub WSL przy użyciu cppdbg typu konfiguracji. W programie Visual Studio 2019 w wersji 16.6 lub nowszej zalecany jest typ cppgdb konfiguracji.

  • name: przyjazna nazwa identyfikującą konfigurację na liście rozwijanej Element startowy.

  • project: określa ścieżkę względną do pliku projektu. Zwykle nie trzeba zmieniać tej wartości podczas debugowania projektu CMake.

  • projectTarget: określa element docelowy narzędzia CMake do wywołania podczas kompilowania projektu. Program Visual Studio automatycznie wypełnia tę właściwość, jeśli wprowadzisz plik launch.vs.json z menu debugowania lub widoku elementów docelowych. Ta wartość musi być zgodna z nazwą istniejącego obiektu docelowego debugowania wymienionego na liście rozwijanej Element startowy.

  • args: Argumenty wiersza polecenia przekazane podczas uruchamiania do debugowanego programu.

  • processID: Identyfikator procesu systemu Linux do dołączenia. Używane tylko podczas dołączania do procesu zdalnego. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z dołączaniem do procesów przy użyciu usługi GDB.

  • program: Wartość domyślna to "${debugInfo.fullTargetPath}". Ścieżka systemu Unix do aplikacji do debugowania. Wymagane tylko wtedy, gdy plik wykonywalny jest inny niż docelowy plik wykonywalny w lokalizacji kompilacji lub wdrożenia.

  • remoteMachineName: Wartość domyślna to "${debugInfo.remoteMachineName}". Nazwa systemu zdalnego, który hostuje program do debugowania. Wymagane tylko wtedy, gdy system kompilacji różni się od systemu kompilacji. Musi mieć istniejący wpis w menedżerze Połączenie ion. Naciśnij klawisze Ctrl+Spacja , aby wyświetlić listę wszystkich istniejących połączeń zdalnych.

  • cwd: Wartość domyślna to "${debugInfo.defaultWorkingDirectory}". Pełna ścieżka systemu Unix do katalogu w systemie zdalnym, w którym program jest uruchamiany. Ten katalog musi istnieć.

  • environment: Dodatkowe zmienne środowiskowe przekazywane do debugowanego programu. Przykład:

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

  • pipeArgs: tablica argumentów wiersza polecenia przekazanych do programu potokowego w celu skonfigurowania połączenia. Program potoku służy do przekazywania standardowych danych wejściowych/wyjściowych między programem Visual Studio i gdb. Większość tej tablicy nie musi być dostosowywana podczas debugowania projektów CMake. Wyjątek to ${debuggerCommand}, który uruchamia się gdb w systemie zdalnym. Można go zmodyfikować w celu:

    • Wyeksportuj wartość zmiennej środowiskowej DISPLAY w systemie Linux. W poniższym przykładzie ta wartość to :1.

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

    • Uruchom skrypt przed wykonaniem polecenia gdb. Upewnij się, że uprawnienia wykonywania są ustawione na skryscie.

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

  • stopOnEntry: wartość logiczna określająca, czy należy przerwać zaraz po uruchomieniu procesu. Wartością domyślną jest false.

  • visualizerFile: plik natvis do użycia podczas debugowania tego procesu. Ta opcja jest niezgodna z ładnym gdb drukowaniem. showDisplayString Ustaw również podczas ustawiania tej właściwości.

  • showDisplayString: wartość logiczna, która włącza ciąg wyświetlania po określeniu elementu visualizerFile . Ustawienie tej opcji może spowodować true niższą wydajność podczas debugowania.

  • setupCommands: Co najmniej jedno gdb polecenie do wykonania w celu skonfigurowania bazowego debugera.

  • miDebuggerPath: pełna ścieżka do gdb. Gdy nie określono, program Visual Studio najpierw wyszukuje ścieżkę dla debugera.

  • Na koniec wszystkie opcje wdrażania zdefiniowane dla cppgdb typu konfiguracji mogą być również używane przez cppdbg typ konfiguracji.

Debugowanie przy użyciu polecenia gdbserver

Konfigurację cppdbg można skonfigurować do debugowania przy użyciu polecenia gdbserver. Więcej szczegółów i przykładowej konfiguracji uruchamiania można znaleźć w blogu zespołu Microsoft C++ w wpisie Debugowanie projektów CMake systemu Linux za pomocą polecenia gdbserver.