ndk-gdb

L'NDK include uno script shell denominato ndk-gdb per avviare una sessione di debug nativo della riga di comando. Gli utenti che preferiscono utilizzare una GUI devono leggere la documentazione relativa al debug in Android Studio.

Requisiti

Affinché il debug nativo della riga di comando funzioni, devono essere soddisfatti i seguenti requisiti:

• Crea la tua app utilizzando lo script ndk-build. Lo script ndk-gdb non supporta l'utilizzo del metodo make APP=<name> legacy per la creazione.
• Attiva il debug delle app nel file AndroidManifest.xml includendo un elemento <application> che imposta l'attributo android:debuggable su true.
• Crea la tua app per l'esecuzione su Android 2.2 (API API di livello 8) o versioni successive.
• Eseguire il debug su un dispositivo o un emulatore con Android 2.2 o versioni successive. Ai fini del debug, il livello API target che hai dichiarato nel file AndroidManifest.xml non è rilevante.
• Sviluppa la tua app in una shell Unix. Su Windows, utilizza Cygwin o l'implementazione sperimentale di ndk-gdb-py Python.
• Utilizza GNU Make 3.81 o versioni successive.

Utilizzo

Per richiamare lo script ndk-gdb, passa alla directory dell'applicazione o a qualsiasi directory sottostante. Ecco alcuni esempi:

cd $PROJECT
$NDK/ndk-gdb

In questo caso, $PROJECT punta alla directory principale del tuo progetto e $NDK rimanda al tuo percorso di installazione NDK.

Quando chiami ndk-gdb, viene configurata la sessione in modo che cerchi i file di origine e le versioni di simboli/debug delle librerie native generate. Dopo il collegamento al processo di applicazione, ndk-gdb genera una lunga serie di messaggi di errore, rilevando che non riesce a trovare le varie librerie di sistema. Questo è normale, perché la tua macchina host non contiene versioni di simboli/debug di queste librerie sul tuo dispositivo di destinazione. Puoi ignorare questi messaggi in tutta sicurezza.

In seguito, ndk-gdb mostra un normale prompt di GDB.

Interagisci con ndk-gdb nello stesso modo in cui interagisci con GNU GDB. Ad esempio, puoi utilizzare b <location> per impostare i punti di interruzione e c (per "continua") per riprendere l'esecuzione. Per un elenco completo dei comandi, consulta il manuale di GDB. Se preferisci utilizzare LLDB Debugger, usa l'opzione --lldb quando chiami lo script ndk-gdb.

Tieni presente che quando esci dalla richiesta di GDB, il processo dell'applicazione di cui esegui il debug si interrompe. Questo comportamento è un limite gdb.

ndk-gdb gestisce molte condizioni di errore e visualizza un messaggio di errore informativo se rileva un problema. Questi controlli includono la verifica delle seguenti condizioni:

• Verifica che ADB sia presente nel tuo percorso.
• Verifica che l'applicazione sia dichiarabile di cui è possibile eseguire il debug nel file manifest.
• Verifica che sul dispositivo sia possibile eseguire il debug anche dell'applicazione installata con lo stesso nome di pacchetto.

Per impostazione predefinita, ndk-gdb cerca un processo dell'applicazione già in esecuzione e, se non ne trova uno, visualizza un errore. Tuttavia, puoi utilizzare l'opzione --start o --launch=<name> per avviare automaticamente l'attività prima della sessione di debug. Per saperne di più, vedi Opzioni.

Opzioni

Per visualizzare un elenco completo delle opzioni, digita ndk-gdb --help nella riga di comando. La tabella 1 mostra una serie di quelli più comunemente utilizzati, insieme a brevi descrizioni.

Tabella 1. Opzioni ndk-gdb comuni e relative descrizioni.

A partire dal giorno ndk-gdb con questa opzione specificata, viene avviata la prima attività avviabile elencata nel manifest dell'applicazione. Usa --launch=<name> per avviare la prossima attività avviabile. Per eseguire il dump dell'elenco delle attività avviabili, esegui --launch-list dalla riga di comando.

Opzione	Descrizione>
--lldb	Se impostato, lo script utilizzerà LLDB Debugger per la sessione anziché gdb.
--verbose	Questa opzione indica al sistema di build di stampare informazioni dettagliate sulla configurazione della sessione di debug nativo. Questa operazione è necessaria solo per problemi di debug quando il debugger non riesce a connettersi all'app e i messaggi di errore visualizzati da ndk-gdb non sono sufficienti.
--force	Per impostazione predefinita, ndk-gdb si interrompe se rileva che un'altra sessione di debug nativa è già in esecuzione sullo stesso dispositivo. Questa opzione termina l'altra sessione e la sostituisce con una nuova. Tieni presente che questa opzione non termina l'app effettiva di cui devi eseguire il debug, che devi eseguire separatamente.
--start	Quando lo avvii, ndk-gdb tenta di collegarsi a un'istanza in esecuzione esistente dell'app sul dispositivo di destinazione per impostazione predefinita. Puoi ignorare questo comportamento predefinito utilizzando --start per avviare in modo esplicito l'applicazione sul dispositivo di destinazione prima della sessione di debug.
--launch=<name>	Questa opzione è simile a --start, con la differenza che ti consente di avviare un'attività specifica dalla tua applicazione. Questa funzionalità è utile solo se il manifest definisce più attività lanciabili.
--launch-list	Questa opzione consente di stampare un elenco dei nomi di tutte le attività disponibili nel file manifest dell'app. --start utilizza il primo nome dell'attività.
--project=<path>	Questa opzione specifica la directory del progetto dell'app. Ciò è utile se vuoi avviare lo script senza prima passare alla directory del progetto.
--port=<port>	Per impostazione predefinita, ndk-gdb utilizza la porta TCP 5039 locale per comunicare con l'app di cui sta eseguendo il debug sul dispositivo di destinazione. L'utilizzo di una porta diversa consente di eseguire il debug nativo dei programmi in esecuzione su diversi emulatori o dispositivi collegati alla stessa macchina host.
--adb=<file>	Questa opzione specifica lo strumento eseguibile adb. Questa operazione è necessaria solo se non hai impostato il tuo percorso per l'esecuzione di questo eseguibile.
-d -e -s <serial>	Questi flag sono simili ai comandi adb con gli stessi nomi. Imposta questi flag se disponi di diversi emulatori o dispositivi connessi alla tua macchina host. Il significato è il seguente: -d Connettiti a un solo dispositivo fisico. -e Connettiti a un singolo emulatore. -s <serial> Connettiti a un dispositivo o emulatore specifico. Qui, <serial> è il nome del dispositivo come indicato dal comando adb devices. In alternativa, puoi definire la variabile di ambiente ADB_SERIAL in modo da elencare un dispositivo specifico, senza dover utilizzare un'opzione specifica.
--exec=<file> -x <file>	Questa opzione indica a ndk-gdb di eseguire i comandi di inizializzazione di GDB trovati in <file> dopo la connessione al processo di debug. Questa è una funzionalità utile se vuoi fare qualcosa di ripetuto, come impostare un elenco di punti di interruzione e riprendere automaticamente l'esecuzione.
--nowait	Disattiva la messa in pausa del codice Java fino alla connessione di GDB. Il superamento di questa opzione potrebbe causare la perdita di punti di interruzione iniziali da parte del debugger.
--tui -t	Attiva l'interfaccia utente di testo, se disponibile.
--gnumake-flag=<flag>	Questa opzione è un flag (o flag) aggiuntivi da passare al sistema ndk-build quando viene eseguita una query per informazioni sul progetto. Puoi utilizzare più istanze di questa opzione nello stesso comando.

Nota: le ultime tre opzioni in questa tabella sono solo per la versione Python di ndk-gdb.

Supporto dei thread

Se la tua app viene eseguita su una piattaforma precedente ad Android 2.3 (livello API 9), ndk-gdb non può eseguire correttamente il debug dei thread nativi. Il debugger può solo eseguire il debug del thread principale, mentre abd ignora completamente l'esecuzione di altri thread.

Se inserisci un punto di interruzione su una funzione eseguita su un thread non principale, il programma esce e GDB visualizza il seguente messaggio:

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