Настройка сеансов отладки CMake

Все исполняемые целевые объекты CMake отображаются в раскрывающемся списке Автозапускаемый элемент в панели инструментов. Чтобы запустить сеанс отладки и отладчик, выберите один из них.

Сеанс отладки можно также запустить из обозревателя решений. Сначала переключитесь на представление диспетчера целевых объектов CMake в окне обозревателя решений.

Затем щелкните исполняемый файл правой кнопкой мыши и выберите Отладка. Эта команда автоматически запускает отладку выбранного целевого объекта на основе активной конфигурации.

Настройка параметров отладчика

Для любого исполняемого объекта CMake в проекте можно настроить параметры отладчика. Они находятся в файле конфигурации с именем launch.vs.json, расположенном в папке .vs в корневом каталоге проекта. Файл конфигурации запуска полезен в большинстве сценариев отладки, так как можно настроить и сохранить сведения о настройке отладки. Этот файл можно открыть тремя способами:

• Меню отладки: Выберите Отладка > Отладка и Параметры запуска для ${activeDebugTarget} в меню main, чтобы настроить конфигурацию отладки, относясь к активному целевому объекту отладки. Если не выбран целевой объект отладки, этот параметр неактивен.

• Представление целевых объектов: перейдите к представлению целевых объектов в обозревателе решений. Затем щелкните правой кнопкой мыши целевой объект отладки и выберите команду Добавить конфигурацию отладки, чтобы настроить конфигурацию отладки для выбранного целевого объекта.

• Корневой файл CMakeLists.txt: щелкните правой кнопкой мыши корневой файл CMakeLists.txt и выберите Добавить конфигурацию отладки, чтобы открыть диалоговое окно Выбор отладчика. В этом диалоговом окне можно добавить любой тип конфигурации отладки, но необходимо вручную указать целевой объект CMake для вызова через свойство projectTarget.

Отредактируйте файл launch.vs.json, чтобы создать конфигурации отладки для любого числа целевых объектов CMake. При сохранении файла Visual Studio создает запись для каждой новой конфигурации в раскрывающемся списке Автозапускаемый элемент.

Ссылки на ключи в CMakeSettings.json

Чтобы сослаться на любой ключ в файле CMakeSettings.json, поставьте перед ним "cmake." в файле launch.vs.json. В следующем примере показан простой файл launch.vs.json, получающий значение ключа "remoteCopySources" в файле CMakeSettings.json для текущей конфигурации:

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

Переменные среды, определенные в CMakeSettings.json, также можно использовать в launch.vs.json с помощью синтаксиса ${env.VARIABLE_NAME}. В Visual Studio 2019 версии 16.4 и более поздней целевые объекты отладки автоматически запускаются с помощью среды, указанной в файле CMakeSettings.json. Переменную среды можно удалить, присвоив ей значение NULL.

Справочник по Launch.vs.json

Существует много свойств launch.vs.json, обеспечивающих поддержку всех сценариев отладки. Следующие свойства являются общими для всех конфигураций отладки, как удаленных, так и локальных.

• projectTarget. Указывает целевой объект CMake, который вызывается при сборке проекта. Visual Studio автоматически заполняет это свойство, если ввести launch.vs.json в меню Отладка или в представлении целевых объектов. Это значение должно совпадать с именем существующего целевого объекта отладки, указанного в раскрывающемся списке Автозапускаемый элемент.

• env. Дополнительные переменные среды для добавления с использованием синтаксиса:

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

• args. Аргументы командной строки, переданные в программу для отладки.

Справочник по Launch.vs.json для удаленных проектов и WSL

В Visual Studio 2019 версии 16.6 добавлена новая конфигурация отладки type: cppgdb, чтобы упростить отладку на удаленных системах и WSL. Старые конфигурации отладки type: cppdbg по-прежнему поддерживаются.

Тип конфигурации cppgdb

• name. Понятное имя для идентификации конфигурации в раскрывающемся списке Автозапускаемый элемент.
• project. Задает относительный путь к файлу проекта. Обычно изменять этот путь при отладке проекта CMake не требуется.
• projectTarget. Указывает целевой объект CMake, который вызывается при сборке проекта. Visual Studio автоматически заполняет это свойство, если ввести launch.vs.json в меню Отладка или в представлении целевых объектов. Это значение целевого объекта должно совпадать с именем существующего целевого объекта отладки, указанного в раскрывающемся списке Автозапускаемый элемент.
• debuggerConfiguration. Указывает набор используемых значений отладки по умолчанию. В Visual Studio 2019 версии 16.6 единственным допустимым параметром является gdb. Visual Studio 2019 версии 16.7 или последующей также поддерживает gdbserver.
• args. Аргументы командной строки, передаваемые при запуске в отлаживаемую программу.
• env. Дополнительные переменные среды, передаваемые в отлаживаемую программу. Например, {"DISPLAY": "0.0"}.
• processID. Идентификатор процесса Linux для присоединения. Используется только при присоединении к удаленному процессу. Дополнительные сведения см. в разделе Устранение неполадок при подключении к процессам с помощью GDB.

Дополнительные параметры для конфигурации gdb

• program. По умолчанию — "${debugInfo.fullTargetPath}". Путь UNIX к приложению для отладки. Требуется только в том случае, если он отличается от целевого исполняемого файла в расположении сборки или развертывания.
• remoteMachineName. По умолчанию — "${debugInfo.remoteMachineName}". Имя удаленной системы, на которой находится программа для отладки. Требуется только в том случае, если оно отличается от системы сборки. Должна иметься существующая запись в диспетчере подключений. Нажмите CTRL + ПРОБЕЛ, чтобы просмотреть список всех существующих удаленных подключений.
• cwd. По умолчанию — "${debugInfo.defaultWorkingDirectory}". Путь UNIX к каталогу в удаленной системе, в которой выполняется program. Этот каталог должен существовать.
• gdbpath. По умолчанию — /usr/bin/gdb. Полный путь UNIX к gdb, используемому для отладки. Требуется только при использовании пользовательской версии gdb.
• preDebugCommand. Команда Linux, которая будет выполняться непосредственно перед вызовом gdb. gdb не запускается до завершения команды. Можно использовать параметр для запуска скрипта перед выполнением gdb.

Дополнительные параметры, поддерживаемые в конфигурации gdbserver (16.7 или последующая версия)

• program. По умолчанию — "${debugInfo.fullTargetPath}". Путь UNIX к приложению для отладки. Требуется только в том случае, если он отличается от целевого исполняемого файла в расположении сборки или развертывания.

  Совет

  Развертывание пока не поддерживается для локальных сценариев перекрестной компиляции. При перекрестной компиляции в Windows (например, при использовании перекрестного компилятора в Windows для создания исполняемого файла Linux ARM) необходимо вручную скопировать двоичный файл в расположение, заданное program на удаленном компьютере ARM перед отладкой.

• remoteMachineName. По умолчанию — "${debugInfo.remoteMachineName}". Имя удаленной системы, на которой находится программа для отладки. Требуется только в том случае, если оно отличается от системы сборки. Должна иметься существующая запись в диспетчере подключений. Нажмите CTRL + ПРОБЕЛ, чтобы просмотреть список всех существующих удаленных подключений.

• cwd. По умолчанию — "${debugInfo.defaultWorkingDirectory}". Полный путь UNIX к каталогу в удаленной системе, в которой выполняется program. Этот каталог должен существовать.

• gdbPath. По умолчанию — ${debugInfo.vsInstalledGdb}. Полный путь Windows к gdb, используемому для отладки. По умолчанию используется gdb, установленный вместе с рабочей нагрузкой "Разработка приложений для Linux на C/C++".

• gdbserverPath. По умолчанию — usr/bin/gdbserver. Полный путь UNIX к gdbserver, используемому для отладки.

• preDebugCommand. Команда Linux, которая будет выполняться непосредственно перед запуском gdbserver. gdbserver не запускается до завершения команды.

Параметры развертывания

Используйте следующие параметры, чтобы отделить компьютер сборки (определенный в CMakeSettings.json) от компьютера удаленной отладки.

• remoteMachineName. Удаленный компьютер для отладки Требуется только в том случае, если оно отличается от компьютера сборки. Должна иметься существующая запись в диспетчере подключений. Нажмите CTRL + ПРОБЕЛ, чтобы просмотреть список всех существующих удаленных подключений.
• disableDeploy. По умолчанию — false. Указывает, отключено ли разделение сборки или отладки. Если указано значение false, этот параметр позволяет выполнять сборку и отладку на двух отдельных компьютерах.
• deployDirectory. Полный путь UNIX к каталогу на remoteMachineName, куда копируется исполняемый файл.
• deploy. Массив дополнительных параметров развертывания. Эти параметры необходимо настроить только в том случае, если требуется более детальный контроль над процессом развертывания. По умолчанию на удаленном компьютере отладки развертываются только файлы, необходимые для процесса отладки.
  • sourceMachine. Компьютер, с которого копируется файл или каталог. Нажмите клавиши CTRL + ПРОБЕЛ, чтобы просмотреть список всех удаленных подключений, хранящихся в диспетчере подключений. При выполнении сборки собственными средствами в WSL этот параметр игнорируется.
  • targetMachine. Компьютер, на который копируется файл или каталог. Нажмите клавиши CTRL + ПРОБЕЛ, чтобы просмотреть список всех удаленных подключений, хранящихся в диспетчере подключений.
  • sourcePath. Расположение файла или каталога на sourceMachine.
  • targetPath. Расположение файла или каталога на targetMachine.
  • deploymentType. Описание типа развертывания. Поддерживаются LocalRemote и RemoteRemote. LocalRemote означает копирование из локальной файловой системы в удаленную систему, заданную remoteMachineName в файле launch.vs.json. RemoteRemote означает копирование из удаленной системы сборки, указанной в файле CMakeSettings.json, в другую удаленную систему, указанную в файле launch.vs.json.
  • executable. Указывает, является ли развернутый файл исполняемым.

Выполнение настраиваемых команд gdb

Visual Studio поддерживает выполнение настраиваемых команд gdb для непосредственного взаимодействия с базовым отладчиком. Дополнительные сведения см. в разделе Выполнение настраиваемых команд gdb lldb.

Включение ведения журнала

Включите ведение журнала MIEngine, чтобы узнать, какие команды отправляются в gdb, какие выходные данные gdb возвращаются и сколько времени занимает выполнение каждой команды. Дополнительные сведения

Тип конфигурации cppdbg

При отладке в удаленной системе или WSL можно использовать следующие параметры, используя тип конфигурации cppdbg. В Visual Studio 2019 версии 16.6 или более поздней рекомендуется конфигурация типа cppgdb.

• name. Понятное имя для идентификации конфигурации в раскрывающемся списке Автозапускаемый элемент.

• project. Задает относительный путь к файлу проекта. Обычно изменять это значение при отладке проекта CMake не требуется.

• projectTarget. Указывает целевой объект CMake, который вызывается при сборке проекта. Visual Studio автоматически заполняет это свойство, если ввести launch.vs.json в меню Отладка или в представлении целевых объектов. Это значение должно совпадать с именем существующего целевого объекта отладки, указанного в раскрывающемся списке Автозапускаемый элемент.

• args. Аргументы командной строки, передаваемые при запуске в отлаживаемую программу.

• processID. Идентификатор процесса Linux для присоединения. Используется только при присоединении к удаленному процессу. Дополнительные сведения см. в разделе Устранение неполадок при подключении к процессам с помощью GDB.

• program. По умолчанию — "${debugInfo.fullTargetPath}". Путь UNIX к приложению для отладки. Требуется только в том случае, если он отличается от целевого исполняемого файла в расположении сборки или развертывания.

• remoteMachineName. По умолчанию — "${debugInfo.remoteMachineName}". Имя удаленной системы, на которой находится программа для отладки. Требуется только в том случае, если оно отличается от системы сборки. Должна иметься существующая запись в диспетчере подключений. Нажмите CTRL + ПРОБЕЛ, чтобы просмотреть список всех существующих удаленных подключений.

• cwd. По умолчанию — "${debugInfo.defaultWorkingDirectory}". Полный путь UNIX к каталогу в удаленной системе, в которой выполняется program. Этот каталог должен существовать.

• environment. Дополнительные переменные среды, передаваемые в отлаживаемую программу. Например, примененная к объекту директива

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

• pipeArgs. Массив аргументов командной строки, переданный в программу канала для настройки подключения. Программа канала используется для ретрансляции стандартных входных и выходных данных между Visual Studio и gdb. Большую часть этого массива не требуется настраивать при отладке проектов CMake. Исключением является ${debuggerCommand}, который запускает gdb в удаленной системе. Его можно изменить для выполнения следующего:

  • Экспорт значения переменной среды 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. Одна или несколько команд gdb для выполнения, чтобы настроить базовый отладчик.

• miDebuggerPath. Полный путь к gdb. Если не указан, Visual Studio сначала ищет путь для отладчика.

• Наконец, все параметры развертывания, определенные для типа конфигурации cppgdb, могут также использоваться типом конфигурации cppdbg.

Отладка с использованием gdbserver

Конфигурацию cppdbg можно настроить для отладки с помощью gdbserver. Дополнительные сведения и пример конфигурации запуска см. в записи блога Microsoft C++ Team Отладка проектов Linux CMake с помощью gdbserver.

См. также

Проекты CMake в Visual Studio.
Настройка проекта Linux CMake
Подключение к удаленному компьютеру Linux
Настройка параметров сборки CMake
Настройка сеансов отладки CMake
Развертывание, запуск и отладка проекта Linux
Справочник по предопределенной конфигурации CMake