Usar depuradores

Esta página detalha o uso do LLDB para desenvolvimento de SO. Para desenvolvimento de apps, consulte Depurar seu app, que explica como usar a GUI do Android Studio (com base no LLDB).

O GDB não é mais fornecido nem tem suporte. Se você estiver trocando do GDB para o LLDB, comece por ler o Tutorial do LLDB. Se você é um usuário avançado do GDB, o mapa de comandos do GDB para o LLDB é muito útil durante a transição.

Pré-requisitos

Para usar um depurador:

• Configure o ambiente de build com o comando envsetup.sh usual.
• Execute o mesmo comando lunch usado na criação. O item de inicialização precisa corresponder exatamente ao dispositivo que você está depurando. Se o item de almoço não corresponder ao dispositivo conectado, você vai receber um erro no formato: You used the wrong lunch: TARGET_PRODUCT (aosp_arm64) does not match attached device (xyzabc)
• Conecte o dispositivo à máquina.

Para mais ajuda com a configuração do ambiente, consulte Configurar o ambiente.

Depurar um binário

Para depurar um binário criado na sua máquina, primeiro você precisa copiar o binário para o dispositivo e, em seguida, iniciar o depurador. Exemplo:

adb push test.exe /data/local/tmp/test.exe
lldbclient.py --port 5038 -r /data/local/tmp/test.exe

Depurar apps ou processos em execução

Para se conectar a um app em execução ou a um daemon nativo, use lldbclient.py com um PID. Por exemplo, para depurar o processo com o PID 1234, execute o seguinte no host:

lldbclient.py -p 1234

O script configura o encaminhamento de portas, inicia o stub de depuração remota adequado no dispositivo, inicia o depurador no host, configura para encontrar símbolos e conecta ao stub de depuração remota.

Depurar a inicialização de processos nativos

Para depurar um processo no início, use lldbclient.py com a opção -r. Por exemplo, para depurar ls /bin, execute o seguinte no host:

lldbclient.py -r /system/bin/ls /bin

Em seguida, insira continue no prompt do depurador.

Depurar a inicialização do app

Às vezes, você quer depurar um app quando ele é iniciado, por exemplo, quando há uma falha e você quer analisar o código para saber o que aconteceu antes da falha. A conexão funciona em alguns casos, mas em outros é impossível porque o app falha antes que você possa fazer a conexão. A abordagem logwrapper (usada para strace) não sempre funciona porque o app pode não ter permissões para abrir uma porta, e o lldbserver herda essa restrição.

Para depurar a inicialização do app, use as opções para desenvolvedores nas Configurações para instruir o app a esperar que um depurador Java seja conectado:

1. Acesse Configurações > Opções do desenvolvedor > Selecionar app de depuração, escolha seu app na lista e clique em Aguardar o depurador.
2. Inicie o app no iniciador ou usando a linha de comando para executar:

   adb shell am start -a android.intent.action.MAIN -n APP_NAME/.APP_ACTIVITY
   

3. Aguarde o carregamento do app e a exibição de uma caixa de diálogo informando que o app está aguardando um depurador.
4. Anexe lldbserver/lldbclient normalmente, defina pontos de interrupção e continue o processo.

Para permitir a execução do app, anexe um depurador do Java Debug Wire Protocol (JDWP), como o Java Debugger (jdb):

adb forward tcp:12345 jdwp:XXX  # (Where XXX is the PID
of the debugged process.)
jdb -attach localhost:12345

Depurar apps ou processos que geram falhas

Se você quiser que o debuggerd suspenda processos com falha para que você possa anexar um depurador, defina a propriedade adequada:

• Após o Android 11

  adb shell setprop debug.debuggerd.wait_for_debugger true
  

• Android 11 e versões anteriores

  adb shell setprop debug.debuggerd.wait_for_gdb true
  

• Android 6.0 Marshmallow e versões anteriores

  adb shell setprop debug.db.uid 999999
  

No final da saída de falha normal, debuggerd fornece instruções de cópia e colagem no Logcat mostrando como conectar o depurador ao processo com falha.

Depurar com o VS Code

O LLDB oferece suporte à depuração de código de plataforma no Visual Studio Code. É possível usar a interface do depurador do VS Code em vez da interface da CLI do LLDB para controlar e depurar o código nativo executado em dispositivos.

Antes de usar o VS Code para depuração, instale a extensão CodeLLDB.

Para depurar o código usando o VS Code:

1. Verifique se todos os artefatos de build (como símbolos) necessários para executar lldbclient.py ou lldbclient.py estão presentes.
2. No VS Code, pressione Ctrl+Shift+P para executar um comando, pesquise Debug: Add Configuration... e selecione LLDB. Isso abre um arquivo launch.json e adiciona um novo objeto JSON a uma lista.
3. Substitua a configuração do depurador recém-adicionada por duas linhas de comentário: // #lldbclient-generated-begin e // #lldbclient-generated-end, para que a lista de configuração fique assim:

   "configurations": [
       // #lldbclient-generated-begin
       // #lldbclient-generated-end
   ]

   O lldbclient.py usa esses comentários para detectar onde gravar a configuração. Se houver outros itens na lista, adicione as linhas de comentário ao final, após as outras configurações.

4. Execute o seguinte comando no terminal em que você executou envsetup.sh e lunch:

   lldbclient.py --setup-forwarding vscode-lldb \
         --vscode-launch-file LAUNCH_JSON_PATH \
         ANY_OTHER_FLAGS -p pid | -n proc-name | -r ...

   lldbclient.py grava a configuração gerada em launch.json e continua em execução. Isso é esperado. Não encerre o programa lldbclient.py. Se você ignorar o --vscode-launch-file, o script vai imprimir o snippet JSON que você vai precisar copiar e colar manualmente em launch.json.

   A flag -r precisa ser a última flag, se estiver presente, devido à forma como as flags são analisadas pela ferramenta.

5. Abra a barra lateral Run and Debug. A nova configuração vai aparecer na lista do depurador. Pressione Iniciar depuração (F5). O depurador precisa se conectar após 10 a 30 segundos.

   Se a nova configuração não aparecer na visualização "Executar e depurar", recarregue a janela para atualizar a lista do depurador: pressione Ctrl + Shift + P e digite reload window.

6. Quando terminar a depuração, acesse o terminal em execução lldbclient.py e pressione Enter para encerrar o programa lldbclient.py. Execuções subsequentes do script gerariam a configuração entre os comentários #lldbclient-generated e substituiriam o conteúdo antigo. Não é necessário removê-los manualmente.

Para adicionar propriedades personalizadas à configuração de inicialização gerada, use a flag --vscode-launch-props. Exemplo:

lldbclient.py --setup-forwarding vscode-lldb \
    --vscode-launch-props \
    '{"initCommands" : ["script print(\"Hello\")"], "preLaunchTask" : "Build"}' \
    ...