Configurar sessões de depuração do CMake

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

A lista suspensa mostra uma lista de destinos de depuração entre os quais escolher. O item selecionado aparece como um botão de reprodução seguido pelo nome do destino de depuração selecionado a ser executado. Neste exemplo, o destino de depuração selecionado é Hello World .exe.

Você também pode iniciar uma sessão de depuração no Gerenciador de Soluções. Primeiro, mude para Vista de Destinos CMake na janela Explorador de Soluções.

O gerenciador de soluções é mostrado. Um clique com o botão direito do rato num item na Vista de Pastas abriu um menu que mostra opções como Abrir, Abrir com, Comparar com e assim por diante. O item de menu Alternar para o Modo de Exibição de Destinos é realçado.

Em seguida, clique com o botão direito do mouse em um executável e selecione Depurar. Este comando inicia automaticamente a depuração do alvo selecionado com base na sua configuração ativa.

Um clique com o botão direito do mouse em um destino na visualização CMake Targets abriu um menu com opções como Definir como item de inicialização, Construir, Limpar tudo e assim por diante. A opção do menu Depurar é realçada.

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

Menu suspenso do projeto é mostrado. A opção de menu para configurar o projeto com o depurador CMake é realçada.

Personalizar as configurações do depurador

Você pode personalizar as configurações do depurador para qualquer destino 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, porque você pode configurar e salvar os detalhes da configuração de depuração. Há três pontos de entrada para este arquivo:

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

do ponto de entrada do menu Depurar

• Exibição de destinos: navegue até de exibição Destinos no Gerenciador de Soluções. Em seguida, clique com o botão direito do rato no destino de depuração e selecione Adicionar Configuração de Depuração para personalizar a configuração de depuração específica para o destino selecionado.

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

Você pode editar o arquivo launch.vs.json para criar configurações de depuração para qualquer número de destinos CMake. Quando o utilizador guarda o ficheiro, o Visual Studio cria uma entrada para cada nova configuração no menu suspenso Item de Inicialização.

Chaves de referência no CMakeSettings.json

Para fazer referência a qualquer chave em um arquivo CMakeSettings.json, anexe cmake. a ela em launch.vs.json. O exemplo a seguir mostra um arquivo launch.vs.json simples que obtém o valor da chave remoteCopySources no arquivo CMakeSettings.json para a configuração selecionada no momento:

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

As 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 posterior, os destinos de depuração são iniciados automaticamente usando o ambiente especificado no CMakeSettings.json. Você pode desdefinir uma variável de ambiente definindo-a como null.

Launch.vs.json referência

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

• projectTarget: Especifica o alvo CMake a ser invocado ao compilar o projeto. O Visual Studio preenche automaticamente esta propriedade se você inserir launch.vs.json a partir do Menu de Depuração ou da Vista 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 adicionais 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.

Launch.vs.json referência para projetos remotos e WSL

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

Tipo de configuração cppgdb

• : Um nome amigável para identificar a configuração no menu suspenso do item de inicialização .
• project: Especifica o caminho relativo para o arquivo de projeto. Normalmente, não precisas alterar este caminho ao depurar um projeto CMake.
• projectTarget: Especifica o alvo CMake a ser invocado ao compilar o projeto. O Visual Studio preenche automaticamente essa propriedade se você inserir launch.vs.json no do Menu de Depuração do ou Exibição de Destinos. Esse valor de destino deve corresponder ao nome de um alvo de depuração existente listado na lista suspensa do 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 oferece suporte a 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 a ser depurado. Por exemplo, {"DISPLAY": "0.0"}.
• processID: ID do processo Linux ao qual se anexar. Apenas usado ao anexar a um processo remoto. Para obter mais informações, consulte Solucionar problemas de anexação a processos usando GDB.

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

• program: O padrão é "${debugInfo.fullTargetPath}". O caminho Unix para o aplicativo a ser depurado. Apenas necessário se for diferente do executável de destino no local de compilação ou implantação.
• remoteMachineName: O valor padrão é definido como "${debugInfo.remoteMachineName}". Nome do sistema remoto que hospeda o programa a depurar. Apenas necessário se for diferente do sistema de compilação. Deve ter uma entrada existente no Connection Manager. Pressione Ctrl+Espaço para exibir uma lista de todas as conexões remotas existentes.
• cwd: O padrão é "${debugInfo.defaultWorkingDirectory}". O caminho Unix para o diretório no sistema remoto onde program é executado. O diretório deve existir.
• gdbpath: O padrão é /usr/bin/gdb. Caminho Unix completo para o gdb utilizado para depuração. Apenas necessário se estiver a utilizar uma versão personalizada do gdb.
• preDebugCommand: Um comando Linux para executar imediatamente antes de invocar gdb. gdb não inicia até que o comando seja 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 gdbserver (16.7 ou posterior)

• program: Assume o valor padrão de "${debugInfo.fullTargetPath}". O caminho Unix para o aplicativo a ser depurado. Apenas necessário se for diferente do executável de destino no local de compilação ou implantação.

  Dica

  A implantação ainda não é suportada para cenários de compilação cruzada local. Se você estiver compilando cruzadamente no Windows (por exemplo, usando um compilador cruzado no Windows para construir um executável Linux ARM), precisará copiar manualmente o binário para o local especificado por program na máquina ARM remota antes da depuração.

• remoteMachineName: O padrão é "${debugInfo.remoteMachineName}". Nome do sistema remoto que hospeda o programa para depuração. Apenas necessário se for diferente do sistema de compilação. Deve ter uma entrada existente no Connection Manager. Pressione Ctrl+Espaço para exibir uma lista de todas as conexões remotas existentes.

• cwd: Por defeito, é "${debugInfo.defaultWorkingDirectory}". Caminho Unix completo para o diretório no sistema remoto onde program é executado. O diretório deve existir.

• gdbPath: Caminho completo do Windows para o gdb usado para depurar.

• gdbserverPath: Define-se por padrão como usr/bin/gdbserver. O caminho Unix completo para o gdbserver usado para debugar.

• preDebugCommand: Um comando Linux para executar imediatamente antes de iniciar gdbserver. gdbserver não inicia até que o comando seja concluído.

Opções de implantação

Use as opções a seguir para separar sua máquina de compilação (definida em CMakeSettings.json) da sua máquina de depuração remota.

• remoteMachineName: Máquina de depuração remota. Apenas necessário se for diferente da máquina de compilação. Deve haver uma entrada existente no Gestor de Conexões. Pressione Ctrl+Espaço para exibir uma lista de todas as conexões remotas existentes.
• disableDeploy: O padrão é false. Indica se a separação entre compilação e depuração está desativada. Quando false, essa opção permite que a compilação e a depuração ocorram em duas máquinas separadas.
• deployDirectory: Caminho Unix completo para o diretório no remoteMachineName para o 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 um controle mais granular sobre o processo de implantação. Por padrão, apenas os arquivos necessários para o processo de depuração são implantados na máquina de depuração remota.
  • sourceMachine: A máquina da qual o arquivo ou diretório é copiado. Pressione Ctrl+Espaço 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: A máquina para a qual o arquivo ou diretório é copiado. Pressione Ctrl+Espaço para exibir uma lista de todas as conexões remotas armazenadas no Gerenciador de Conexões.
  • sourcePath: O local do arquivo ou diretório no sourceMachine.
  • targetPath: O local do arquivo ou diretório no targetMachine.
  • deploymentType: Uma descrição do tipo de implantação. LocalRemote e RemoteRemote são suportados. 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 compilação 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 gdb personalizados

O Visual Studio oferece suporte à execução de comandos gdb personalizados para interagir diretamente com o depurador subjacente. Para obter mais informações, consulte Executando comandos personalizados gdb lldb.

Ativar registo

Habilite o log do MIEngine para ver 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 dropdown do Item de Inicialização .

• project: Especifica o caminho relativo para o arquivo de projeto. Normalmente, você não precisa alterar esse valor ao depurar um projeto CMake.

• projectTarget: Especifica o alvo CMake a ser invocado ao compilar o projeto. O Visual Studio preenche automaticamente essa propriedade se você inserir launch.vs.json no do Menu de Depuração do ou 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 Linux para anexar. Usado apenas ao ligar a um processo remoto. Para obter mais informações, consulte Solucionar problemas de anexação a processos usando GDB.

• program: Usa o padrão "${debugInfo.fullTargetPath}". O caminho Unix para o aplicativo a ser depurado. Apenas necessário se for diferente do executável de destino no local de compilação ou implantação.

• remoteMachineName: Por defeito, é "${debugInfo.remoteMachineName}". Nome do sistema remoto que aloja o programa a depurar. Apenas necessário se for diferente do sistema de compilação. Deve ter uma entrada existente no Connection Manager. Pressione Ctrl+Espaço para exibir uma lista de todas as conexões remotas existentes.

• cwd: O padrão é "${debugInfo.defaultWorkingDirectory}". Caminho Unix completo para o diretório no sistema remoto onde program é executado. O diretório deve existir.

• environment: Variáveis de ambiente adicionais passadas para o programa em depuração. 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 de pipe é usado para retransmitir entrada/saída padrão entre o Visual Studio e gdb. A maior parte desta matriz não precisa ser personalizada ao depurar projetos CMake. A exceção é o ${debuggerCommand}, que lança gdb no sistema remoto. Pode ser modificado para:

  • Exporte o valor da variável de ambiente DISPLAY no 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. Certifique-se de que 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 valor booleano que especifica se deve ser interrompido logo que o processo é iniciado. O padrão é "false".

• visualizerFile: Um arquivo .natvis usar ao depurar este processo. Esta opção é incompatível com gdb formatação legível. Também defina showDisplayString ao definir esta propriedade.

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

• setupCommands: Um ou mais gdb comando(s) para executar, para configurar o depurador subjacente.

• miDebuggerPath: O caminho completo para gdb. Quando não especificado, o Visual Studio procura primeiro no PATH pelo depurador.

• Finalmente, 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 ajustar a configuração cppdbg para depurar usando gdbserver. Você pode encontrar mais detalhes e uma configuração de inicialização de exemplo na postagem do blog da equipe do Microsoft C++ Debugging Linux CMake Projects with gdbserver.

Ver também

projetos CMake no Visual Studio
Configurar um projeto CMake Linux
Conecte-se ao seu computador Linux remoto
Personalizar as configurações de compilação do CMake
Configurar sessões de depuração do CMake
Implante, execute e depure seu projeto Linux
Referência de configuração predefinida do CMake