Depurar o app

O Android Studio oferece um depurador que permite fazer o seguinte e muito mais:

• Selecionar um dispositivo para depurar o app.
• Definir pontos de interrupção no seu código Java, Kotlin e C/C++.
• Examinar as variáveis e avaliar as expressões no tempo de execução.

Esta página inclui instruções para operações básicas do depurador. Para conferir outras documentações, consulte também os documentos de depuração IntelliJ IDEA (link em inglês).

Ativar a depuração

Antes de começar a depuração, faça o seguinte:

Ative a depuração no dispositivo.

Se você estiver usando o emulador, ela estará ativada por padrão. No entanto, em um dispositivo conectado, é necessário ativar a depuração nas opções do desenvolvedor no dispositivo.

Execute uma variante de build depurável.

Use uma variante de build que inclua debuggable true (isDebuggable = true em scripts Kotlin) na configuração do build.

Normalmente, é possível selecionar a variante padrão "debug" incluída em todo projeto do Android Studio, mesmo que não esteja visível no arquivo build.gradle. No entanto, se você definir novos tipos de build que precisam ser depuráveis, adicione debuggable true ao tipo de build:

Groovy

android {
    buildTypes {
        customDebugType {
            debuggable true
            ...
        }
    }
}

Kotlin

android {
    buildTypes {
        create("customDebugType") {
            isDebuggable = true
            ...
        }
    }
}

Essa propriedade também se aplica a módulos com código C/C++.

Observação: a propriedade jniDebuggable não é mais usada.

Caso seu app dependa de um módulo de biblioteca que você também queira depurar, a biblioteca também precisa ser empacotada com debuggable true para que ela retenha os símbolos de depuração. Para garantir que as variantes depuráveis do seu projeto de app recebam a variante depurável de um módulo de biblioteca, publique versões não padrão da sua biblioteca.

Começar a depurar

É possível começar uma sessão de depuração desta forma:

1. Defina pontos de interrupção no código do app.
2. Na barra de ferramentas, selecione um dispositivo para depurar o app no menu do dispositivo de destino.

   

   Se você não tiver nenhum dispositivo configurado, será necessário conectar um dispositivo por USB, conectar um dispositivo por Wi-Fi ou criar um AVD para usar o Android Emulator.

3. Na barra de ferramentas, clique em Debug .

   Se o app já estiver em execução no dispositivo, uma caixa de diálogo será mostrada perguntando se você quer alternar de "Run" para "Debug". O dispositivo precisará ser reiniciado para começar a depuração. Para manter a mesma instância do app em execução, clique em Cancel Debug e anexe o depurador a um app em execução. Caso contrário, o Android Studio vai criar um APK, assiná-lo com uma chave de depuração, instalá-lo no dispositivo selecionado e executá-lo.

   Se você adicionar um código C e C++ ao seu projeto, o Android Studio também executará o depurador LLDB (link em inglês) na janela "Debug" para depurar seu código nativo.

4. Se a janela de depuração não estiver aberta, selecione View > Tool Windows > Debug ou clique em Debug na barra da janela de ferramentas.

Anexar o depurador a um app em execução

Se o app já estiver em execução no dispositivo, você poderá começar a depuração sem reiniciá-lo:

1. Clique em Attach debugger to Android process .
2. Na caixa de diálogo Choose Process, selecione o processo a que você quer conectar o depurador.
   1. Se estiver usando um emulador ou um dispositivo com acesso root, selecione Show all processes para conferir todos os processos. Em um dispositivo com acesso root, isso vai mostrar todos os processos em execução no dispositivo. No entanto, em um dispositivo sem acesso root, essa opção só vai mostrar processos depuráveis.
   2. No menu Use Android Debugger Settings from, é possível selecionar uma configuração de execução/depuração existente. Para código C e C++, isso permite reutilizar os comandos de inicialização do LLDB, os comandos de pós-vinculação do LLDB e os diretórios de símbolos de uma configuração existente.
   3. Se você não tiver uma configuração de execução/depuração existente, selecione Create New. Essa seleção ativa o menu Debug Type, em que você pode selecionar um tipo de depuração diferente. Por padrão, o Android Studio usa o tipo de depuração "Detect Automatically" para selecionar a melhor opção de depurador para você com base na presença de código Java ou C/C++ no seu projeto.
3. Clique em OK.

   A janela "Debug" vai aparecer.

A guia Processes no Device Explorer (View > Tool Windows > Device Explorer) também tem uma lista de processos depuráveis. Nela, é possível selecionar um processo e encerrar , forçar o fechamento ou anexar o depurador a um determinado processo .

A janela de depuração

A janela de depuração é dividida em

1. Barra de ferramentas de execução e navegação. Consulte Trabalhar com pontos de interrupção
2. Seletor de thread
3. Entrada de expressão de avaliação e observação. Consulte Inspecionar variáveis.
4. Pilha
5. Painel "Variables" Consulte Inspecionar variáveis.

Observação: o depurador e o coletor de lixo do Android Studio são relativamente integrados. A máquina virtual do Android garante que todos os objetos visíveis pelo depurador não sejam coletados até que o depurador seja desconectado. Isso pode resultar em um acúmulo de objetos enquanto o depurador estiver conectado. Por exemplo, se o depurador detectar uma linha de execução em funcionamento, o objeto Thread associado não será coletado até que o depurador seja desconectado, mesmo se a linha de execução for encerrada.

Mudar o tipo de depurador

Como diferentes ferramentas do depurador são necessárias para depurar código Java/Kotlin e código C/C++, o depurador do Android Studio permite selecionar o tipo de depurador a ser usado. Por padrão, o Android Studio decide qual depurador usar pelas linguagens detectadas do seu projeto usando o tipo de depurador Detect Automatically.

Para selecionar manualmente o depurador na configuração de depuração, clique em Run > Edit Configurations. Também é possível selecionar o depurador na caixa de diálogo mostrada ao clicar em Run > Attach debugger to Android process.

Os tipos de depuração disponíveis incluem:

Detect Automatically

Selecione esse tipo de depuração caso queira que o Android Studio escolha automaticamente a melhor opção para o código sendo depurado. Por exemplo, caso seu app inclua código C ou C++ no projeto, o Android Studio vai usar o tipo de depuração Dual automaticamente. Caso contrário, o Android Studio usará o tipo de depuração Java.

Somente Java

Selecione esse tipo de depuração caso queira depurar somente o código em Java ou Kotlin. O depurador Somente Java ignora todos os pontos de interrupção ou controle definidos no código nativo.

Somente Native (disponível apenas para código C/C++)

Selecione esse tipo de depuração caso queira usar apenas o LLDB para depurar seu código. Ao usar esse tipo de depuração, a visualização da sessão do depurador Java não estará disponível. Por padrão, o LLDB inspeciona apenas seu código nativo e ignora os pontos de interrupção no seu código Java. Se você também quiser depurar o código Java, alterne para o tipo de depuração "Detect Automatically" ou "Dual".

O modo de depuração "Native" só funciona em dispositivos que atendem a estes requisitos:

• O dispositivo oferece suporte a run-as.

  Para verificar se o dispositivo é compatível com run-as, execute o seguinte comando no shell do ADB conectado ao dispositivo:

  run-as your-package-name pwd
  

  Substitua your-package-name pelo nome do pacote do seu app. Se o dispositivo for compatível com run-as, o comando retornará sem erros.

• O ptrace está ativado no dispositivo.

  Para verificar se o ptrace está ativado, execute o seguinte comando no shell do ADB conectado ao dispositivo:

  sysctl kernel.yama.ptrace_scope
  

  Se ptrace estiver ativado, o comando vai mostrar o valor 0 ou um erro unknown key. Se ptrace não estiver ativado, um valor diferente de 0 será exibido.

Dual (Java + Native): disponível apenas com código C/C++

Selecione esse tipo de depuração se quiser alternar entre a depuração de código nativo e Java. O Android Studio conecta os depuradores Java e LLDB ao processo do seu app. Assim, é possível inspecionar os pontos de interrupção no código Java e no código nativo sem reiniciar o app ou mudar a configuração de depuração.

Na Figura 2, observe as duas guias à direita do título da janela Debug. Como o app tem código Java e C++, uma guia serve para depurar o código nativo e a outra para o código Java, conforme indicado por -java.

Observação: ao depurar código nativo otimizado pelo compilador, você pode receber esta mensagem de aviso:
This function was compiled with optimizations enabled. Some debugger features may not be available. Ao usar sinalizações de otimização, o compilador muda seu código compilado para torná-lo mais eficiente. Isso pode fazer com que o depurador passe informações inesperadas e incorretas, já que é difícil para o depurador mapear o código compilado otimizado de volta para o código-fonte original. Por esse motivo, ao depurar seu código nativo, desative as otimizações de compilador.

Usar o registro do sistema

O registro do sistema mostra mensagens do sistema enquanto você depura seu app. Elas incluem informações sobre os apps em execução no dispositivo. Caso queira usar o registro do sistema para depurar seu app, seu código precisa gravar mensagens de registro e exibir o stack trace para exceções enquanto o app estiver na fase de desenvolvimento.

Gravar mensagens de registro no código

Para gravar mensagens de registro no seu código, use a classe Log. As mensagens de registro ajudam você a entender o fluxo de execução ao coletar a saída de depuração do sistema enquanto você interage com seu app. Elas também podem informar qual parte do app apresenta falhas. Para saber mais sobre a geração de registros, consulte Gravar e visualizar registros com o Logcat.

O exemplo abaixo mostra como adicionar mensagens de registro para determinar se há informações de estado anterior disponíveis quando sua atividade for iniciada:

Kotlin

import android.util.Log
...
class MyActivity : Activity() {
    ...
    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        if (savedInstanceState != null) {
            Log.d(TAG, "onCreate() Restoring previous state")
            /* restore state */
        } else {
            Log.d(TAG, "onCreate() No saved state available")
            /* initialize app */
        }
        ...
    }
  ...
  companion object {
    private val TAG: String = MyActivity::class.java.simpleName
    ...
  }
}

Java

import android.util.Log;
...
public class MyActivity extends Activity {
    private static final String TAG = MyActivity.class.getSimpleName();
    ...
    @Override
    public void onCreate(Bundle savedInstanceState) {
       ...
       if (savedInstanceState != null) {
            Log.d(TAG, "onCreate() Restoring previous state");
            /* restore state */
        } else {
            Log.d(TAG, "onCreate() No saved state available");
            /* initialize app */
        }
        ...
    }
}

Durante o desenvolvimento, seu código também pode identificar exceções e gravar o stack trace no registro do sistema:

Kotlin

fun someOtherMethod() {
    try {
        ...
    } catch (e : SomeException) {
        Log.d(TAG, "someOtherMethod()", e)
    }
}

Java

void someOtherMethod() {
    try {
        ...
    } catch (SomeException e) {
        Log.d(TAG, "someOtherMethod()", e);
    }
}

Observação: remova as mensagens de registro de depuração e as chamadas de exibição de stack trace do seu código quando o app estiver pronto para ser publicado. Para fazer isso, defina uma sinalização DEBUG e insira mensagens de registro de depuração em instruções condicionais.

Conferir o registro do sistema

Você pode conferir e filtrar a depuração e outras mensagens do sistema na janela do Logcat, conforme mostrado na Figura 4. Por exemplo, é possível conferir mensagens quando a coleta de lixo ocorre ou as mensagens adicionadas ao app com a classe Log.

Para usar o Logcat, comece a depuração e selecione a guia "Logcat".

Consulte Gravar e visualizar registros com o Logcat para descrições do Logcat e as opções de filtragem.

Trabalhar com pontos de interrupção

O Android Studio oferece suporte a pontos de interrupção que acionam diferentes ações de depuração. Há vários tipos de ponto de interrupção:

Ponto de interrupção de linha

O tipo mais comum é um ponto de interrupção de linha que interrompe a execução do seu app quando ele chega a uma linha de código especificada. Durante a pausa, é possível examinar variáveis, avaliar expressões e continuar a execução linha por linha para determinar as causas de erros no ambiente de execução.

Ponto de interrupção de método

Um ponto de interrupção de método pausa a execução do app quando ele entra ou sai de um método específico. Durante a pausa, é possível examinar variáveis, avaliar expressões e continuar a execução linha por linha para determinar as causas de erros no ambiente de execução. Quando você define um ponto de interrupção em uma função combinável, o depurador lista os parâmetros do elemento combinável e o estado deles para ajudar a identificar quais mudanças podem ter causado a recomposição.

Ponto de interrupção de campo

Um ponto de interrupção de campo pausa a execução do app quando ele lê ou grava em um campo específico.

Ponto de interrupção de exceção

Um ponto de interrupção de exceção pausa a execução do app quando uma exceção é gerada.

É possível definir pontos de interrupção condicionais que vão suspender a execução apenas se condições específicas forem atendidas. Você também pode definir pontos de interrupção de registro que gravam no Logcat sem suspender a execução. Isso ajuda a evitar o excesso de log statements no código.

Para adicionar um ponto de interrupção de linha, faça o seguinte:

1. Localize a linha de código em que você quer pausar a execução.
2. Clique na margem esquerda dessa linha ou posicione o cursor na linha e pressione Control + F8 (no macOS, Command + F8).
3. Se o app já estiver em execução, clique em Attach debugger to Android process . Caso contrário, para iniciar a depuração, clique em Debug .

Um ponto vermelho aparece ao lado da linha depois de definir um ponto de interrupção, como mostrado na figura 5.

Quando a execução do seu código atinge o ponto de interrupção, o Android Studio pausa a execução do app.

Para identificar o estado do app, use as ferramentas na guia "Debugger":

• Para examinar a árvore de objetos de uma variável, expanda-a na visualização "Variables". Se a visualização "Variables" não estiver disponível, clique em Layout Settings e verifique se a opção variables está marcada.

• Para avançar para a próxima linha do código sem inserir um método, clique em Step Over .

• Para avançar para a primeira linha dentro de uma chamada de método, clique em Step Into .

• Para avançar para a próxima linha fora do método atual, clique em Step Out .

• Para continuar executando o app normalmente, clique em Resume Program .

Caso seu projeto use código nativo, por padrão, o tipo de depuração "Detect Automatically" vai conectar o depurador Java e o LLDB ao seu app como dois processos separados. Você pode alternar entre inspecionar os pontos de interrupção Java e C/C++ sem reiniciar o app nem mudar as configurações.

Observação: para que o Android Studio detecte pontos de interrupção no seu código C ou C++, use um tipo de depuração compatível com o LLDB, como Detect Automatically, Native ou Dual. Mude o tipo de depuração usado pelo Android Studio editando sua configuração de depuração. Para saber mais sobre os diferentes tipos de depuração, leia a seção sobre como usar outros tipos de depuração.

Quando o Android Studio implanta seu app no dispositivo de destino, a janela "Debug" aparece com uma guia ou com uma visualização de sessão de depuração para cada processo de depuração, conforme mostrado na figura 6.

1. O Android Studio alterna para a guia <your-module> quando o depurador LLDB encontra um ponto de interrupção no código C/C++. Os painéis "Frames", "Variables" e "Watches" também estão disponíveis e funcionam exatamente como funcionariam se você estivesse depurando código Java.

   Embora o painel "Threads" não esteja disponível na visualização da sessão do LLDB, é possível acessar os processos do app com a lista suspensa do painel "Frames". Saiba mais sobre esses painéis nas seções sobre como depurar frames de janela e inspecionar variáveis.

   Observação: ao inspecionar um ponto de interrupção no seu código nativo, o sistema Android suspende a máquina virtual que executa o bytecode Java do app. Isso significa que não é possível interagir com o depurador Java nem extrair informações de estado da sessão de depuração Java ao inspecionar um ponto de interrupção no código nativo.

2. O Android Studio automaticamente alterna para a guia <your-module>-java quando o depurador Java encontra um ponto de interrupção no código Java ou Kotlin.
3. Ao depurar com LLDB, você pode usar o terminal do LLDB na visualização da sessão para transmitir opções de linha de comando para o LLDB (link em inglês). Se quiser que o LLDB execute comandos específicos sempre que você iniciar a depuração do app, antes ou depois de conectar o depurador ao processo do seu app, você pode adicionar esses comandos à configuração de depuração.

Enquanto você depura o código C/C++, também é possível definir tipos especiais de pontos de interrupção, chamados pontos de controle, que podem suspender o processo do seu app quando ele interage com um bloco de memória específico. Para saber mais, leia a seção sobre como adicionar pontos de controle.

Conferir e configurar pontos de interrupção

Para conferir todos os pontos de interrupção e definir as configurações, clique em View Breakpoints na janela "Debug". A janela Breakpoints vai aparecer, conforme mostrado na Figura 7.

A janela "Breakpoints" permite ativar ou desativar cada ponto de interrupção da lista no painel. Se um ponto de interrupção for desativado, o Android Studio não pausará o app quando ele alcançar esse ponto.

Selecione um ponto de interrupção na lista para definir as configurações. É possível configurar um ponto de interrupção para ser desativado inicialmente e fazer com que o sistema o ative depois que outro ponto de interrupção for alcançado. Também é possível configurar se um ponto de interrupção precisa ser desativado depois de ser alcançado. Para definir um ponto de interrupção para qualquer exceção, selecione Exception Breakpoints na lista de pontos de interrupção.

Para desativar temporariamente todos os pontos de interrupção, clique em Mute Breakpoints na janela de depuração. Clique novamente para reativar.

Depurar frames de janela

Na janela "Debugger", o painel "Frames" permite inspecionar o frame da pilha que fez com que o ponto de interrupção atual fosse alcançado. É possível navegar e examinar o frame da pilha e inspecionar a lista de linhas de execução no seu app Android.

Para selecionar uma linha de execução, use o menu do seletor e confira o frame da pilha. Clique nos elementos no frame para abrir a fonte no editor. Também é possível personalizar a apresentação da linha de execução e exportar o frame da pilha conforme discutido no Guia sobre examinar frames (link em inglês).

Inspecionar variáveis

Na janela "Debugger", o painel "Variables" permite inspecionar variáveis quando o sistema interrompe seu app em um ponto de interrupção e você seleciona um frame no painel "Frames". O painel "Variables" também permite avaliar expressões ad-hoc usando métodos e/ou variáveis estáticos disponíveis no frame selecionado.

Para adicionar uma expressão à árvore de objetos (enquanto o aplicativo está sendo depurado):

1. Insira a expressão a ser observada ou mostrada
2. Clique em Add to watches ou pressione Enter para avaliar a expressão uma vez.

Como alternativa, se a árvore de objetos contiver a expressão que você quer monitorar, arraste-a para a parte de cima da árvore para adicioná-la como uma expressão monitorada.

As expressões monitoradas serão atualizadas quando os pontos de interrupção forem atingidos ou você passar pelo código.

As expressões avaliadas vão permanecer na parte de cima da árvore de objetos até que você avalie manualmente outra expressão ou passe pelo código.

Para remover uma expressão observada da árvore de objetos, clique com o botão direito do mouse na expressão e clique em Remove Watch.

Adicionar pontos de controle

Durante a depuração do código C/C++, é possível definir tipos especiais de pontos de interrupção chamados pontos de controle, que suspendem o processo do app quando ele interage com um bloco de memória específico. Por exemplo: se você definir dois ponteiros para um bloco de memória e atribuir um ponto de controle a ele, o uso de qualquer um desses ponteiros para acessar esse bloco de memória acionará o ponto de controle.

No Android Studio, é possível selecionar uma variável específica para criar um ponto de controle no ambiente de execução. Entretanto, o LLDB atribui o ponto de controle apenas para o bloco de memória que o sistema aloca para a variável, não para a variável em si. Isso é diferente de adicionar uma variável ao painel "Watches", o que permite observar o valor de uma variável, mas não suspender o processo do app quando o sistema ler ou mudar o valor dele na memória.

Observação: quando o processo do app sai de uma função e o sistema desaloca as variáveis locais da memória, é necessário reatribuir todos os pontos de controle criados para essas variáveis.

Para definir um ponto de controle, é preciso atender aos seguintes requisitos:

• O dispositivo ou emulador de destino precisa usar uma CPU de x86 ou x86_64. Se o dispositivo usar uma CPU ARM, será necessário alinhar o limite do endereço da variável na memória como 4 bytes para processadores de 32 bits ou 8 bytes para processadores de 64 bits. Para alinhar uma variável no código nativo, especifique __attribute__((aligned(num_bytes))) na desaceleração da variável, conforme mostrado abaixo:

  // For a 64-bit ARM processor
  int my_counter __attribute__((aligned(8)));
  

• Você já alinhou três pontos de controle ou menos. O Android Studio aceita até quatro pontos de controle em dispositivos de destino de x86 ou x86_64. Outros dispositivos podem aceitar menos pontos de controle.

Observação: ao depurar seu app com ABIs ARM de 32 bits, adicionar um ponto de controle ou passar o cursor sobre as variáveis no código para conferir os valores delas pode causar uma falha. Como solução alternativa, faça a depuração usando binários ARM, x86 ou x86_64 de 64 bits. Esse problema será corrigido em uma versão futura do Android Studio.

Se você atender aos requisitos, poderá adicionar um ponto de controle desta forma:

1. Enquanto seu app estiver suspenso em um ponto de interrupção, acesse o painel "Variables" na visualização da sua sessão do LLDB.

2. Clique com o botão direito do mouse em uma variável que ocupa o bloco de memória que você quer rastrear e selecione Add Watchpoint.

   

3. Uma caixa de diálogo para configurar seu ponto de controle vai aparecer, conforme mostrado na Figura 9.

   Configure seu ponto de controle com as seguintes opções:

   • Enabled: desmarque essa opção se quiser que o Android Studio ignore o ponto de controle até que você mude a configuração. O Android Studio salva seu ponto de controle para que você possa acessá-lo mais tarde.
   • Suspend: por padrão, o sistema Android suspende o processo do seu app quando ele acessa um bloco de memória atribuído a um ponto de controle. Desmarque essa opção se não quiser que isso aconteça. Isso revela outras opções que podem ser usadas para personalizar o comportamento quando o sistema interage com o ponto de controle: Log message to console e Remove when hit.
   • Access Type: selecione essa opção caso seu app precise acionar o ponto de controle quando tentar ler ou gravar no bloco de memória que o sistema alocar para a variável. Para acionar o ponto de controle em uma ação de leitura ou gravação, selecione Any.
4. Clique em Concluído.

Para conferir todos os pontos de controle e definir as configurações, clique em View Breakpoints na janela de depuração. A caixa de diálogo Breakpoints vai aparecer, conforme mostrado na Figura 10.

Depois de adicionar um ponto de controle, clique em Resume Program na janela "Debug" para retomar o processo do seu app. Por padrão, se o app tentar acessar um bloco de memória para que você atribuiu um ponto de controle, o sistema Android vai suspender o processo do app e um ícone de ponto de controle aparecerá ao lado da última linha de código executada, conforme mostrado na Figura 11.

Conferir e mudar o formato de exibição dos valores de recursos

No modo de depuração, é possível conferir os valores dos recursos e selecionar um formato de exibição diferente para variáveis no seu código Java ou Kotlin. Com a guia "Variables" mostrada e um frame selecionado, faça o seguinte:

1. Na lista "Variables", clique com o botão direito do mouse em qualquer lugar de uma linha de recurso para mostrar a lista.
2. Na lista, selecione View as e escolha o formato que você quer usar.

   Os formatos disponíveis dependem do tipo de dado do recurso selecionado. Você poderá encontrar uma ou mais destas opções:

   • Class: mostra a definição da classe.
   • toString: exibe o formato da string.
   • Object: exibe a definição de objeto (uma instância de uma classe).
   • Array: exibe em um formato de matriz.
     
   • Timestamp: exibe a data e a hora como aaaa-mm-dd hh:mm:ss.
   • Auto: o Android Studio escolhe o melhor formato com base no tipo de dado.
     
   • Binary: exibe um valor binário usando 0 e 1.
   • MeasureSpec: o valor passado do pai para o filho selecionado. Consulte MeasureSpec.
   • Hex: exibe como um valor hexadecimal.
   • Primitive: mostra como um valor numérico usando um tipo de dado primitivo.
   • Integer: mostra um valor numérico do tipo Integer.

Para criar um formato personalizado, faça o seguinte:

1. Clique no valor do recurso com o botão direito do mouse.
2. Selecione View as.
3. Selecione Create.
4. A caixa de diálogo Java Data Type Renderers vai aparecer. Siga as instruções em Renderizadores de tipos de dados Java (link em inglês).