Configurar sessões de depuração do CMake

  • Artigo

O suporte ao CMake nativo está disponível no Visual Studio 2017 e posterior. Para ver a documentação dessas versões, defina o controle seletor de Versão do Visual Studio deste artigo para o Visual Studio 2017 ou posterior. Ele é encontrado na parte superior da tabela de conteúdo nesta página.

Todos os destinos de CMake executáveis são mostrados na lista suspensa Item de Inicialização na barra de ferramentas. Selecione uma opção para iniciar uma sessão de depuração e iniciar o depurador.

Screenshot of the CMake startup items dropdown.

Inicie também uma sessão de depuração por meio dos menus do Gerenciador de Soluções. Primeiro, alterne para a Exibição de Destinos do CMake na janela Gerenciador de Soluções.

Screenshot of the CMake Targets View menu.

Então clique com o botão direito do mouse em um executável e selecione Depurar. Esse comando inicia automaticamente a depuração do destino selecionado com base na configuração ativa.

Screenshot of the CMake Targets View debug option menu.

A partir do Visual Studio 2022 Versão 17.6, você também pode iniciar uma sessão de depuração no arquivo .txt CMakeLists. Para fazer isso, basta definir um ponto de interrupção no arquivo CMakeLists.txt e executar Configurar projeto com o depurador CMake na lista suspensa Projeto .

Screenshot of the CMake Debugger dropdown.

Personalizar configurações do depurador

Você pode personalizar as configurações do depurador para qualquer destino do CMake executável em seu projeto. Eles são encontrados em um arquivo de configuração chamado launch.vs.json, localizado em uma pasta .vs na raiz do projeto. Um arquivo de configuração de inicialização é útil na maioria dos cenários de depuração, pois você pode configurar e salvar os detalhes da configuração de depuração. Há três pontos de entrada neste arquivo:

  • Menu Depurar: selecione Depurar > Configurações de Depuração e Inicialização para ${activeDebugTarget} no menu principal para personalizar a configuração de depuração específica para o destino de depuração ativo. Se você não tiver um destino de depuração selecionado, essa opção estará esmaecida.

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

  • Exibição de destinos: navegue até a Exibição de Destinos no Gerenciador de Soluções. Então clique com o botão direito do mouse em um destino de depuração e selecione Adicionar Configuração de Depuração para personalizar a configuração de depuração específica ao destino selecionado.

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

  • CMakeLists.txt raiz: clique com o botão direito do mouse em um CMakeLists.txt raiz e selecione Adicionar Configuração de Depuração para abrir a caixa de diálogo Selecionar um Depurador. A caixa de diálogo permite adicionar qualquer tipo de configuração de depuração, mas você deve especificar manualmente o destino CMake a ser invocado por meio da propriedade projectTarget.

Screenshot of the Select a debugger dialog box.

Você pode editar o arquivo launch.vs.json para criar configurações de depuração para qualquer número de destinos do CMake. Quando você salva o arquivo, o Visual Studio cria uma entrada para cada nova configuração na lista suspensa Item de Inicialização.

Chaves de referência em CMakeSettings.json

Para fazer referência a qualquer chave em um arquivo CMakeSettings.json, acrescente cmake. antes dela em launch.vs.json. O seguinte exemplo mostra um arquivo launch.vs.json simples que extrai o valor da chave remoteCopySources no arquivo CMakeSettings.json da configuração atualmente selecionada:

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

Variáveis de ambiente definidas em CMakeSettings.json também podem ser usadas em launch.vs.json usando a sintaxe ${env.VARIABLE_NAME}. No Visual Studio 2019 versão 16.4 e posteriores, os destinos de depuração são iniciados automaticamente usando o ambiente especificado em CMakeSettings.json. Você pode remover a definição de uma variável de ambiente definindo-a como nula.

Referência Launch.vs.json

Há muitas propriedades launch.vs.json para dar suporte a todos os cenários de depuração. As seguintes propriedades são comuns a todas as configurações de depuração, tanto remotas quanto locais:

  • projectTarget: especifica o destino CMake a ser invocado ao compilar o projeto. O Visual Studio preencherá automaticamente essa propriedade se você inserir launch.vs.json no Menu de Depuração ou no Modo de Exibição de Destinos. Esse valor deve corresponder ao nome de um destino de depuração existente listado na lista suspensa Item de Inicialização.

  • env: variáveis de ambiente extras a serem adicionadas usando a sintaxe:

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

  • args: argumentos de linha de comando passados para o programa para depuração.

Referência launch.vs.json para projetos remotos e WSL

No Visual Studio 2019 versão 16.6, adicionamos uma configuração de depuração de type: cppgdb para simplificar a depuração em sistemas remotos e WSL. Configurações antigas de depuração de type: cppdbg ainda são compatíveis.

Tipo de configuração cppgdb

  • name: um nome amigável para identificar a configuração na lista suspensa Item de Inicialização.
  • project: especifica o caminho relativo para o arquivo de projeto. Normalmente, você não precisa alterar esse caminho ao depurar um projeto CMake.
  • projectTarget: especifica o destino CMake a ser invocado ao compilar o projeto. O Visual Studio preencherá automaticamente essa propriedade se você inserir launch.vs.json no Menu de Depuração ou no Modo de Exibição de Destinos. Esse valor de destino deve corresponder ao nome de um destino de depuração listado na lista suspensa Item de Inicialização.
  • debuggerConfiguration: indica qual conjunto de valores padrão de depuração usar. No Visual Studio 2019 versão 16.6, a única opção válida é gdb. O Visual Studio 2019 versão 16.7 ou posterior também dá suporte para gdbserver.
  • args: argumentos de linha de comando passados na inicialização para o programa que está sendo depurado.
  • env: variáveis de ambiente adicionais passadas para o programa que está sendo depurado. Por exemplo, {"DISPLAY": "0.0"}.
  • processID: ID do processo do Linux à qual anexar. Usado somente ao anexar a um processo remoto. Para mais informações, confira Solucionar problemas de anexação a processos usando GDB.

Opções adicionais para a configuração gdb

  • program: usa "${debugInfo.fullTargetPath}" como padrão. O caminho Unix para o aplicativo a ser depurado. Necessário apenas se diferente do executável de destino no local de build ou implantação.
  • remoteMachineName: usa "${debugInfo.remoteMachineName}" como padrão. Nome do sistema remoto que hospeda o programa para depurar. Necessário somente se diferente do sistema de build. Deve ter uma entrada no Gerenciador de Conexões. Pressione Ctrl+Space para exibir uma lista de todas as conexões remotas.
  • cwd: usa "${debugInfo.defaultWorkingDirectory}" como padrão. O caminho do Unix para o diretório no sistema remoto em que program é executado. O diretório precisa existir.
  • gdbpath: usa /usr/bin/gdb como padrão. Caminho completo do Unix para o gdb usado para depurar. Necessário apenas se estiver usando uma versão personalizada de gdb.
  • preDebugCommand: um comando Linux a ser executado imediatamente antes de invocar gdb. gdb não começa até o comando ser concluído. Você pode usar a opção para executar um script antes da execução de gdb.

Opções adicionais permitidas com a configuração de gdbserver (16.7 ou posterior)

  • program: usa "${debugInfo.fullTargetPath}" como padrão. O caminho Unix para o aplicativo a ser depurado. Necessário apenas se diferente do executável de destino no local de build ou implantação.

    Dica

    A implantação ainda não tem suporte para cenários locais de compilação cruzada. Se você estiver compilando de modo cruzado no Windows (por exemplo, usando um compilador cruzado no Windows para criar um executável do ARM do Linux), precisará copiar manualmente o binário para o local especificado pelo program no computador ARM remoto antes da depuração.

  • remoteMachineName: usa "${debugInfo.remoteMachineName}" como padrão. Nome do sistema remoto que hospeda o programa para depurar. Necessário somente se diferente do sistema de build. Deve ter uma entrada no Gerenciador de Conexões. Pressione Ctrl+Space para exibir uma lista de todas as conexões remotas.

  • cwd: usa "${debugInfo.defaultWorkingDirectory}" como padrão. Caminho completo do Unix para o diretório no sistema remoto em que program é executado. O diretório precisa existir.

  • gdbPath: usa ${debugInfo.vsInstalledGdb} como padrão. Caminho completo do Windows para o gdb usado para depurar. O padrão é o gdb instalado com o desenvolvimento do Linux com carga de trabalho C/C++.

  • gdbserverPath: usa usr/bin/gdbserver como padrão. Caminho completo do Unix para o gdbserver usado para depurar.

  • preDebugCommand: um comando Linux a ser executado imediatamente antes de iniciar gdbserver. gdbserver não começa até o comando ser concluído.

Opções de implantação

Use as opções a seguir para separar o computador de build (definido em CMakeSettings.json) do computador de depuração remoto.

  • remoteMachineName: computador de depuração remoto. Necessário somente se diferente do computador de build. Deve ter uma entrada no Gerenciador de Conexões. Pressione Ctrl+Space para exibir uma lista de todas as conexões remotas.
  • disableDeploy: usa false como padrão. Indica se a separação de build/depuração está desabilitada. Quando false, essa opção permite que o build e a depuração ocorram em dois computadores separados.
  • deployDirectory: caminho completo do Unix para o diretório em remoteMachineName no qual o executável é copiado.
  • deploy: uma matriz de configurações avançadas de implantação. Você só precisa definir essas configurações quando quiser ter um controle mais granular sobre o processo de implantação. Por padrão, somente os arquivos necessários para depurar o processo são implantados no computador de depuração remoto.
    • sourceMachine: o computador do qual o arquivo ou diretório é copiado. Pressione Ctrl+Space para exibir uma lista de todas as conexões remotas armazenadas no Gerenciador de Conexões. Ao criar nativamente no WSL, essa opção é ignorada.
    • targetMachine: o computador para o qual o arquivo ou diretório é copiado. Pressione Ctrl+Space para exibir uma lista de todas as conexões remotas armazenadas no Gerenciador de Conexões.
    • sourcePath: o local do arquivo ou diretório em sourceMachine.
    • targetPath: o local do arquivo ou diretório em targetMachine.
    • deploymentType: uma descrição do tipo de implantação. Há suporte para LocalRemote e RemoteRemote. LocalRemote significa copiar do sistema de arquivos local para o sistema remoto especificado por remoteMachineName em launch.vs.json. RemoteRemote significa copiar do sistema de build remoto especificado em CMakeSettings.json para o sistema remoto diferente especificado em launch.vs.json.
    • executable: indica se o arquivo implantado é um executável.

Executar comandos personalizados gdb

O Visual Studio dá suporte à execução de comandos gdb personalizados para interagir diretamente com o depurador subjacente. Para mais informações, confira Como executar comandos gdb lldb personalizados.

Habilitar o registro em log do

Habilite o registro em log do MIEngine para ver para quais comandos são enviados para gdb, qual saída gdb retorna e quanto tempo cada comando leva. Saiba mais

Tipo de configuração cppdbg

As opções a seguir podem ser usadas ao depurar em um sistema remoto ou WSL usando o tipo de configuração cppdbg. No Visual Studio 2019 versão 16.6 ou posterior, o tipo de configuração cppgdb é recomendado.

  • name: um nome amigável para identificar a configuração na lista suspensa Item de Inicialização.

  • project: especifica o caminho relativo para o arquivo de projeto. Normalmente, não é necessário alterar esse valor ao depurar um projeto CMake.

  • projectTarget: especifica o destino CMake a ser invocado ao compilar o projeto. O Visual Studio preencherá automaticamente essa propriedade se você inserir launch.vs.json no Menu de Depuração ou no Modo de Exibição de Destinos. Esse valor deve corresponder ao nome de um destino de depuração existente listado na lista suspensa Item de Inicialização.

  • args: argumentos de linha de comando passados na inicialização para o programa que está sendo depurado.

  • processID: ID do processo do Linux à qual anexar. Usado somente ao anexar a um processo remoto. Para mais informações, confira Solucionar problemas de anexação a processos usando GDB.

  • program: usa "${debugInfo.fullTargetPath}" como padrão. O caminho Unix para o aplicativo a ser depurado. Necessário apenas se diferente do executável de destino no local de build ou implantação.

  • remoteMachineName: usa "${debugInfo.remoteMachineName}" como padrão. Nome do sistema remoto que hospeda o programa para depurar. Necessário somente se diferente do sistema de build. Deve ter uma entrada no Gerenciador de Conexões. Pressione Ctrl+Space para exibir uma lista de todas as conexões remotas.

  • cwd: usa "${debugInfo.defaultWorkingDirectory}" como padrão. Caminho completo do Unix para o diretório no sistema remoto em que program é executado. O diretório precisa existir.

  • environment: variáveis de ambiente adicionais passadas para o programa que está sendo depurado. Por exemplo,

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

  • pipeArgs: uma matriz de argumentos de linha de comando passados para o programa de pipe para configurar a conexão. O programa pipe é usado para retransmitir entrada/saída padrão entre o Visual Studio e gdb. A maior parte dessa matriz não precisa ser personalizada ao depurar projetos do CMake. A exceção é a ${debuggerCommand}inicialização gdb no sistema remoto. Ele pode ser modificado para:

    • Exporte o valor da variável de ambiente DISPLAY em seu sistema Linux. No exemplo a seguir, esse valor é :1.

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

    • Execute um script antes da execução de gdb. Verifique se as permissões de execução estão definidas no script.

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

  • stopOnEntry: um booliano que especifica se o processo será interrompido assim que o processo for iniciado. O padrão é false.

  • visualizerFile: um arquivo .natvis a ser usado ao depurar esse processo. Essa opção é incompatível com reformatação automática gdb. Também defina showDisplayString ao definir essa propriedade.

  • showDisplayString: um booliano que habilita a cadeia de caracteres de exibição quando um visualizerFile é especificado. Definir essa opção como true pode tornar o desempenho mais lento durante a depuração.

  • setupCommands: um ou mais comandos gdb para executar, para configurar o depurador subjacente.

  • miDebuggerPath: o caminho completo para gdb. Quando não especificado, o Visual Studio pesquisa PATH primeiro para o depurador.

  • Por fim, todas as opções de implantação definidas para o tipo de configuração cppgdb também podem ser usadas pelo tipo de configuração cppdbg.

Depurar usando gdbserver

Você pode definir a configuração cppdbg para depuração usando gdbserver. Encontre mais detalhes e uma configuração de inicialização de exemplo na postagem no blog da equipe do Microsoft C++ Como depurar projetos do CMake do Linux com gdbserver.