Configuración de sesiones de depuración de CMake

  • Artículo

La compatibilidad con CMake nativo está disponible en Visual Studio 2017 y versiones posteriores. Para ver la documentación de estas versiones, establezca el control de selector de Versión de Visual Studio para este artículo en Visual Studio 2017 o versiones posteriores. Se encuentra en la parte superior de la tabla de contenido de esta página.

Todos los destinos de CMake ejecutables se muestran en la lista desplegable Elemento de inicio en la barra de herramientas. Seleccione una para empezar una sesión de depuración e iniciar el depurador.

Screenshot of the CMake startup items dropdown.

También se puede iniciar una sesión de depuración desde el Explorador de soluciones. En primer lugar, cambie a Vista de destinos de CMake en la ventana Explorador de soluciones.

Screenshot of the CMake Targets View menu.

Después, haga clic con el botón derecho en un ejecutable y seleccione Depurar. Este comando inicia automáticamente la depuración del destino seleccionado en función de la configuración activa.

Screenshot of the CMake Targets View debug option menu.

A partir de la versión 17.6 de Visual Studio 2022, también puede iniciar una sesión de depuración en el archivo CMakeLists.txt. Para ello, solo tiene que establecer un punto de interrupción en el archivo CMakeLists.txt y ejecutar Configurar proyecto con el depurador de CMake en la lista desplegable Proyecto .

Screenshot of the CMake Debugger dropdown.

Personalización de la configuración del depurador

Se puede personalizar la configuración del depurador para cualquier destino de CMake ejecutable en el proyecto. Se encuentran en un archivo de configuración denominado launch.vs.json, ubicado en una carpeta .vs en la raíz del proyecto. Un archivo de configuración de inicio resulta útil en la mayoría de los escenarios de depuración, ya que se pueden configurar y guardar la información de configuración de la depuración. Hay tres puntos de entrada a este archivo:

  • Debug Menu: seleccione Depurar > Configuración de depuración e inicio para ${activeDebugTarget} en el menú principal para personalizar la configuración de depuración específica de su destino de depuración activo. Si no se tiene un destino de depuración seleccionado, esta opción aparece atenuada.

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

  • Vista Destinos: vaya a La vista Destinos en Explorador de soluciones. Luego, haga clic con el botón derecho en un destino de depuración y seleccione Agregar configuración de depuración para personalizar la configuración de depuración específica para el destino seleccionado.

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

  • Root CMakeLists.txt: haga clic con el botón derecho en una raíz CMakeLists.txt y seleccione Agregar configuración de depuración para abrir el cuadro de diálogo Seleccionar un depurador . El cuadro de diálogo permite agregar cualquier tipo de configuración de depuración, pero debe especificar manualmente el destino de CMake que se va a invocar a través de la propiedad projectTarget.

Screenshot of the Select a debugger dialog box.

Se puede editar el archivo launch.vs.json a fin de crear configuraciones de depuración para cualquier número de destinos de CMake. Al guardar el archivo, Visual Studio crea una entrada para cada configuración nueva en la lista desplegable Elemento de inicio.

Claves de referencia en CMakeSettings.json

Para hacer referencia a cualquier clave en un archivo CMakeSettings.json, debe anteponer cmake. a este en launch.vs.json. En el ejemplo siguiente se muestra un archivo launch.vs.json simple que extrae el valor de la clave remoteCopySources en el archivo CMakeSettings.json para la configuración seleccionada actualmente:

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

Las variables de entorno definidas en CMakeSettings.json también se pueden usar en launch.vs.json con la sintaxis ${env.VARIABLE_NAME}. En Visual Studio 2019, versión 16.4 y posteriores, los destinos de depuración se inician automáticamente con el entorno que se especifique en CMakeSettings.json. Se puede desactivar una variable de entorno al establecerla en Null.

Referencia de launch.vs.json

Hay muchas propiedades de launch.vs.json para admitir todos los escenarios de depuración. Las propiedades siguientes son comunes a todas las configuraciones de depuración, tanto remotas como locales:

  • projectTarget: especifica el destino de CMake que se va a invocar al compilar el proyecto. Visual Studio rellena automáticamente esta propiedad si escribe launch.vs.json desde el Menú Depurar o Vista de destinos. Este valor debe coincidir con el nombre de un destino de depuración existente que aparezca en la lista desplegable Elemento de inicio.

  • env: variables de entorno adicionales que se van a agregar mediante la sintaxis:

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

  • args: argumentos de línea de comandos pasados al programa para depurar.

Referencia de launch.vs.json para proyectos remotos y WSL

En la versión 16.6 de Visual Studio 2019 hemos agregado una nueva configuración de depuración de type: cppgdb para simplificar la depuración en sistemas remotos y WSL. Todavía se admiten las configuraciones de depuración antiguas de type: cppdbg.

Tipo de configuración cppgdb

  • name: nombre descriptivo para identificar la configuración en la lista desplegable Elemento de inicio.
  • project: especifica la ruta de acceso relativa al archivo del proyecto. Normalmente, no es necesario cambiar esta ruta de acceso al depurar un proyecto de CMake.
  • projectTarget: especifica el destino de CMake que se va a invocar al compilar el proyecto. Visual Studio rellena automáticamente esta propiedad si escribe launch.vs.json desde el Menú Depurar o Vista de destinos. Este valor de destino debe coincidir con el nombre de un destino de depuración existente que aparezca en la lista desplegable Elemento de inicio.
  • debuggerConfiguration: indica qué conjunto de valores predeterminados de depuración se van a usar. En la versión 16.6 de Visual Studio 2019, la única opción válida es gdb. Visual Studio 2019 versión 16.7 o posterior también admite gdbserver.
  • args: argumentos de línea de comandos pasados al inicio al programa que se está depurando.
  • env: variables de entorno adicionales que se pasan al programa que se está depurando. Por ejemplo, {"DISPLAY": "0.0"}.
  • processID: identificador de proceso de Linux al que se va a asociar. Solo se usa cuando se adjunta a un proceso remoto. Para obtener más información, vea Solución de problemas de asociación a procesos mediante GDB.

Opciones adicionales para la configuración de gdb

  • program: Tiene como valor predeterminado "${debugInfo.fullTargetPath}". Ruta de acceso de Unix a la aplicación que se va a depurar. Solo es necesaria si es diferente del ejecutable de destino en la ubicación de compilación o implementación.
  • remoteMachineName: Tiene como valor predeterminado "${debugInfo.remoteMachineName}". Nombre del sistema remoto que hospeda el programa que se va a depurar. Solo es necesaria si es diferente del sistema de compilación. Debe tener una entrada existente en el Administrador de conexiones. Presione Ctrl+Espacio para ver una lista de todas las conexiones remotas existentes.
  • cwd: Tiene como valor predeterminado "${debugInfo.defaultWorkingDirectory}". Ruta de acceso de Unix al directorio del sistema remoto donde se ejecuta program. El directorio debe existir.
  • gdbpath: Tiene como valor predeterminado /usr/bin/gdb. Ruta de acceso completa de Unix al elemento gdb que se usa para depurar. Solo es necesaria si se usa una versión personalizada de gdb.
  • preDebugCommand: comando de Linux que se ejecutará inmediatamente antes de invocar gdb. gdb no se inicia hasta que se completa el comando. Se puede usar la opción para ejecutar un script antes de la ejecución de gdb.

Opciones adicionales permitidas con la configuración del elemento gdbserver (16.7 o posterior)

  • program: Tiene como valor predeterminado "${debugInfo.fullTargetPath}". Ruta de acceso de Unix a la aplicación que se va a depurar. Solo es necesaria si es diferente del ejecutable de destino en la ubicación de compilación o implementación.

    Sugerencia

    Todavía no se admite la implementación para los escenarios de compilación cruzada local. Si va a realizar una compilación cruzada en Windows (por ejemplo, mediante un compilador cruzado en Windows para compilar un ejecutable de ARM de Linux), deberá copiar manualmente el archivo binario en la ubicación especificada por program en la máquina remota de ARM antes de la depuración.

  • remoteMachineName: Tiene como valor predeterminado "${debugInfo.remoteMachineName}". Nombre del sistema remoto que hospeda el programa que se va a depurar. Solo es necesaria si es diferente del sistema de compilación. Debe tener una entrada existente en el Administrador de conexiones. Presione Ctrl+Espacio para ver una lista de todas las conexiones remotas existentes.

  • cwd: Tiene como valor predeterminado "${debugInfo.defaultWorkingDirectory}". Ruta de acceso de Unix al directorio del sistema remoto donde se ejecuta program. El directorio debe existir.

  • gdbPath: Tiene como valor predeterminado ${debugInfo.vsInstalledGdb}. Ruta de acceso completa de Windows al elemento gdb que se usa para depurar. El valor predeterminado es el elemento gdb instalado con la carga de trabajo de desarrollo de Linux con C/C++.

  • gdbserverPath: Tiene como valor predeterminado usr/bin/gdbserver. Ruta de acceso completa de Unix al elemento gdbserver que se usa para depurar.

  • preDebugCommand: comando de Linux que se ejecutará inmediatamente antes de iniciar gdbserver. gdbserver no se inicia hasta que se completa el comando.

Opciones de implementación

Use las opciones siguientes para separar la máquina de compilación (definida en CMakeSettings.json) de la máquina de depuración remota.

  • remoteMachineName: máquina de depuración remota. Solo es necesaria si es diferente de la máquina de compilación. Debe tener una entrada existente en el Administrador de conexiones. Presione Ctrl+Espacio para ver una lista de todas las conexiones remotas existentes.
  • disableDeploy: Tiene como valor predeterminado false. Indica si la separación entre la compilación y la depuración está deshabilitada. Cuando su valor es false, esta opción permite que la compilación y la depuración se produzcan en dos máquinas independientes.
  • deployDirectory: ruta de acceso completa de Unix al directorio en remoteMachineName el que se copia el ejecutable.
  • deploy: matriz de opciones de implementación avanzadas. Solo se tienen que configurar estos valores si se quiere un control más granular sobre el proceso de implementación. De forma predeterminada, solo los archivos necesarios para depurar el proceso se implementan en la máquina de depuración remota.
    • sourceMachine: la máquina desde la que se copia el archivo o directorio. Presione Ctrl+Espacio para ver una lista de todas las conexiones remotas almacenadas en el Administrador de conexiones. Al compilar de forma nativa en WSL, se omite esta opción.
    • targetMachine: la máquina a la que se copia el archivo o directorio. Presione Ctrl+Espacio para ver una lista de todas las conexiones remotas almacenadas en el Administrador de conexiones.
    • sourcePath: la ubicación del archivo o directorio en sourceMachine.
    • targetPath: la ubicación del archivo o directorio en targetMachine.
    • deploymentType: una descripción del tipo de implementación. Se admiten LocalRemote y RemoteRemote. LocalRemote significa copiar del sistema de archivos local al sistema remoto que especifica remoteMachineName en launch.vs.json. RemoteRemote significa copiar del sistema de compilación remoto especificado en CMakeSettings.json al sistema remoto especificado en launch.vs.json.
    • executable: indica si el archivo implementado es un ejecutable.

Ejecución de comandos de gdb personalizados

Visual Studio admite la ejecución de comandos de gdb personalizados para interactuar directamente con el depurador subyacente. Para obtener más información, vea Ejecución de los comandos de lldb gdb personalizados.

Habilitación del registro

Habilite el registro de MIEngine para ver qué comandos se envían a gdb, qué salida gdb devuelve y cuánto tiempo tarda cada comando. Más información

Tipo de configuración cppdbg

Se pueden usar las opciones siguientes al depurar en un sistema remoto o WSL con el tipo de configuración cppdbg. En la versión 16.6, o una posterior, de Visual Studio 2019, se recomienda el tipo de configuración cppgdb.

  • name: nombre descriptivo para identificar la configuración en la lista desplegable Elemento de inicio.

  • project: especifica la ruta de acceso relativa al archivo del proyecto. Normalmente, no es necesario cambiar este valor al depurar un proyecto de CMake.

  • projectTarget: especifica el destino de CMake que se va a invocar al compilar el proyecto. Visual Studio rellena automáticamente esta propiedad si escribe launch.vs.json desde el Menú Depurar o Vista de destinos. Este valor debe coincidir con el nombre de un destino de depuración existente que aparezca en la lista desplegable Elemento de inicio.

  • args: argumentos de línea de comandos pasados al inicio al programa que se está depurando.

  • processID: identificador de proceso de Linux al que se va a asociar. Solo se usa cuando se adjunta a un proceso remoto. Para obtener más información, vea Solución de problemas de asociación a procesos mediante GDB.

  • program: Tiene como valor predeterminado "${debugInfo.fullTargetPath}". Ruta de acceso de Unix a la aplicación que se va a depurar. Solo es necesaria si es diferente del ejecutable de destino en la ubicación de compilación o implementación.

  • remoteMachineName: Tiene como valor predeterminado "${debugInfo.remoteMachineName}". Nombre del sistema remoto que hospeda el programa que se va a depurar. Solo es necesaria si es diferente del sistema de compilación. Debe tener una entrada existente en el Administrador de conexiones. Presione Ctrl+Espacio para ver una lista de todas las conexiones remotas existentes.

  • cwd: Tiene como valor predeterminado "${debugInfo.defaultWorkingDirectory}". Ruta de acceso de Unix al directorio del sistema remoto donde se ejecuta program. El directorio debe existir.

  • environment: variables de entorno adicionales que se pasan al programa que se está depurando. Por ejemplo,

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

  • pipeArgs: matriz de argumentos de línea de comandos pasados al programa de canalización para configurar la conexión. El programa de canalización se usa para retransmitir la entrada/salida estándar entre Visual Studio y gdb. No es necesario personalizar la mayor parte de esta matriz al depurar proyectos de CMake. La excepción es ${debuggerCommand}, que inicia gdb en el sistema remoto. Se puede modificar a lo siguiente:

    • Exportar el valor de la variable de entorno DISPLAY en el sistema Linux. En el ejemplo siguiente, este valor es :1.

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

    • Ejecutar un script antes de la ejecución de gdb. Asegúrese de que los permisos de ejecución están establecidos en el script.

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

  • stopOnEntry: un valor booleano que especifica si se interrumpirá tan pronto como se inicie el proceso. El valor predeterminado es false.

  • visualizerFile: un archivo .natvis que se va a usar al depurar este proceso. Esta opción no es compatible con la impresión con sangría gdb. Establezca también showDisplayString al establecer esta propiedad.

  • showDisplayString: un valor booleano que habilita la cadena de presentación cuando se especifica .visualizerFile Establecer esta opción en true puede ralentizar el rendimiento durante la depuración.

  • setupCommands: uno o varios gdb comandos que se van a ejecutar, para configurar el depurador subyacente.

  • miDebuggerPath: ruta de acceso completa a gdb. Cuando no se especifica, Visual Studio busca en primer lugar PATH para el depurador.

  • Por último, el tipo de configuración cppdbg también puede usar todas las opciones de implementación definidas para el tipo de configuración cppgdb.

Depuración mediante gdbserver

La configuración de cppdbg se puede configurar para depurar con gdbserver. Puede encontrar más detalles y una configuración de inicio de ejemplo en la entrada del Blog del equipo de Microsoft C++ Depuración de proyectos de CMake en Linux con gdbserver.