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

Статья
10/26/2023

Встроенная поддержка CMake реализована в Visual Studio версии 2017 и выше. Чтобы увидеть документацию для этих версий, установите в данной статье селектор Версия Visual Studio в Visual Studio 2017 и более поздних версий. Он находится в верхней части оглавления на этой странице.

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

Снимок экрана: раскрывающийся список элементов запуска CMake.

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

Снимок экрана: меню

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

Снимок экрана: меню параметров отладки для просмотра целевых объектов CMake.

Начиная с Visual Studio 2022 версии 17.6, вы также можете запустить сеанс отладки в файле CMakeLists.txt. Для этого просто задайте точку останова в файле CMakeLists.txt и запустите проект с помощью отладчика CMake из раскрывающегося списка "Проект ".

Снимок экрана: раскрывающийся список отладчика CMake.

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

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

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

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

Снимок экрана: команда

Корневой 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

Поделиться через

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

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

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

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

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

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

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

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

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

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

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

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

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

См. также

Обратная связь

Дополнительные ресурсы

Поделиться через

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

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

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

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

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

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

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

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

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

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

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

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

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

См. также

Обратная связь

Дополнительные ресурсы

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

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

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

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

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

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