Esta página foi traduzida pela API Cloud Translation.

ndk-gdb

O NDK inclui um script de shell chamado ndk-gdb para iniciar uma sessão de depuração nativa da linha de comando. Os usuários que preferem usar uma GUI precisam ler a documentação sobre depuração no Android Studio.

Requisitos

Para que a depuração nativa da linha de comando funcione, estes requisitos precisam ser atendidos:

Crie seu app usando o script ndk-build. O script ndk-gdb não é compatível com o uso do métodomake APP=<name> legado para criar.
Ative a depuração do app no arquivo AndroidManifest.xml, incluindo um elemento <application> que defina o atributo android:debuggable como true.
Crie seu app para ser executado no Android 2.2 (API do Android de nível 8) ou versões mais recentes.
Depure em um dispositivo ou emulador que execute o Android 2.2 ou versões mais recentes. Para fins de depuração, o nível da API selecionado que você declara no arquivo AndroidManifest.xml não é importante.
Desenvolva seu app em um shell do Unix. No Windows, use Cygwin ou a implementação Python experimental de ndk-gdb-py (links em inglês).
Use o GNU Make 3.81 ou versão mais recente.

Uso

Para invocar o script ndk-gdb, mude para o diretório do app ou qualquer diretório dentro dele. Exemplo:

cd $PROJECT
$NDK/ndk-gdb

Nesse exemplo, $PROJECT aponta para o diretório raiz do seu projeto, e $NDK aponta para o caminho de instalação do NDK.

Quando você invoca ndk-gdb, ele configura a sessão para buscar arquivos de origem e versões de símbolo/depuração das suas bibliotecas nativas geradas. Depois de anexado ao processo do app, o ndk-gdb produz uma longa série de mensagens de erro notificando que não foi possível encontrar diversas bibliotecas do sistema. Isso é normal, porque a máquina host não contém versões de símbolo/depuração dessas bibliotecas no dispositivo de destino. Você pode ignorar totalmente essas mensagens.

Em seguida, ndk-gdb exibe uma solicitação normal do GDB.

A interação com ndk-gdb ocorre da mesma forma que com o GDB GNU. Por exemplo, é possível usar b <location> para definir pontos de interrupção e c (de "continuar") para retomar a execução. Para ver uma lista completa de comandos, consulte o manual do GDB (link em inglês). Se você preferir usar o LLDB Debugger (link em inglês), use a opção --lldb ao invocar o script ndk-gdb.

Quando você sai da solicitação do GDB, o processo do app que está sendo depurado é interrompido. Esse comportamento é uma limitação do GDB.

ndk-gdb processa muitas condições de erro e exibe uma mensagem de erro informativa se encontra algum problema. Essas verificações incluem garantir que as condições a seguir sejam atendidas:

Verifica se o adb está no seu caminho.
Verifica se o app está declarado como depurável no manifesto.
Verifica, no dispositivo, se o app instalado com o mesmo nome de pacote também é depurável.

Por padrão, ndk-gdb busca um processo de app já em execução e exibe um erro caso não encontre um. No entanto, você pode usar a opção --start ou --launch=<name> para iniciar automaticamente sua atividade antes da sessão de depuração. Para saber mais, consulte Opções.

Opções

Para ver uma lista completa de opções, digite ndk-gdb --help na linha de comando. A Tabela 1 mostra várias das opções mais comumente usadas, com descrições breves.

Tabela 1. Opções comuns de ndk-gdb e as descrições delas.

Iniciar ndk-gdb com essa opção especificada inicializa a primeira atividade inicializável listada no manifesto do seu app. Use --launch=<name> para iniciar a próxima atividade inicializável. Para fazer o despejo da lista de atividades inicializáveis, execute --launch-list na linha de comando.

Opção	Descrição>
`--lldb`	Se definida, o script usará o LLDB Debugger para a sessão em vez do GDB.
`--verbose`	Essa opção manda o sistema de build gerar informações detalhadas sobre a configuração da sessão de depuração nativa. Ela é necessária somente para problemas de depuração quando o depurador não consegue se conectar ao app e as mensagens de erro que `ndk-gdb` exibe não são suficientes.
`--force`	Por padrão, `ndk-gdb` faz o cancelamento se descobre que há outra sessão de depuração nativa em execução no mesmo dispositivo. Essa opção encerra e substitui a outra sessão por uma nova. Observe que essa opção não encerra o app em depuração, que você precisa encerrar separadamente.
`--start`	Por padrão, quando você inicia o `ndk-gdb`, ele tenta se conectar a uma instância já em execução do seu app no dispositivo de destino. É possível modificar esse comportamento padrão usando `--start` para inicializar o app explicitamente no dispositivo antes da sessão de depuração.
`--launch=<name>`	Essa opção é parecida com `--start`, mas permite iniciar uma atividade específica pelo app. Esse recurso só é útil se o manifesto tiver definido diversas atividades inicializáveis.
`--launch-list`	Essa opção conveniente gera uma lista com o nome de todas as atividades inicializáveis encontradas no manifesto do app. `--start` usa o primeiro nome da atividade.
`--project=<path>`	Essa opção especifica o diretório do projeto do app. Ela é útil se você quiser inicializar o script sem precisar acessar primeiro o diretório do projeto.
`--port=<port>`	Por padrão, `ndk-gdb` usa a porta TCP 5039 local para se comunicar com o app que está depurando no dispositivo de destino. Usar uma porta diferente permite depurar nativamente programas em execução em diferentes dispositivos ou emuladores conectados à mesma máquina host.
`--adb=<file>`	Essa opção especifica a ferramenta adb executável. Ela só é necessária se você não tiver definido o caminho para incluir esse executável.
`-d` `-e` `-s <serial>`	Essas sinalizações são parecidas com os comandos adb de mesmo nome. Ative essas sinalizações se houver vários dispositivos ou emuladores conectados à máquina host. As funções deles são as seguintes: `-d` Conectar-se a um único dispositivo físico. `-e` Conectar-se a um único dispositivo de emulação. `-s <serial>` Conectar-se a um dispositivo ou emulador específico. Aqui, `<serial>` é o nome do dispositivo conforme listado pelo comando `adb devices`. Como alternativa, você pode configurar a variável de ambiente `ADB_SERIAL` para listar um dispositivo específico, sem precisar de nenhuma opção especial.
`--exec=<file>` `-x <file>`	Essa opção manda o `ndk-gdb` executar os comandos de inicialização do GDB encontrados em `<file>` após a conexão com o processo em depuração. Esse é um recurso útil se você quer fazer algo repetidas vezes, como configurar uma lista de pontos de interrupção e depois retomar a execução automaticamente.
`--nowait`	Impede a pausa do código em Java até o GDB se conectar. Transmitir essa opção pode fazer com que o depurador perca os pontos de interrupção iniciais.
`--tui` `-t`	Ativa a interface de texto do usuário, se houver.
`--gnumake-flag=<flag>`	Essa opção é uma sinalização extra (ou sinalizações) que será transmitida ao sistema do `ndk-build` ao consultá-lo quanto a informações do projeto. É possível usar diversas instâncias dessa opção no mesmo comando.

Observação: as três últimas opções nessa tabela são apenas para a versão Python de ndk-gdb.

Compatibilidade com linha de execução

Se o app for executado em uma plataforma anterior ao Android 2.3 (API de nível 9), o ndk-gdb não conseguirá depurar linhas de execução nativas da forma correta. O depurador só pode depurar a linha de execução principal, e o adb ignora completamente a execução das outras linhas.

Se você colocar um ponto de interrupção em uma função executada em uma linha de execução que não seja a principal, o programa será fechado e o GDB exibirá a seguinte mensagem:

Program terminated with signal SIGTRAP, Trace/breakpoint trap.
      The program no longer exists.