ndk-gdb

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

Requisiti

Affinché il debug nativo a 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> precedente per la compilazione.
  • Attiva il debug dell'app nel file AndroidManifest.xml includendo un elemento <application> che imposta l'attributo android:debuggable su true.
  • Compila l'app in modo che venga eseguita su Android 2.2 (livello API Android 8) o versioni successive.
  • Esegui il debug su un dispositivo o un emulatore con Android 2.2 o versioni successive. A scopo di debug, il livello API target dichiarato nel file AndroidManifest.xml non è importante.
  • Sviluppa l'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, vai alla directory dell'applicazione o a qualsiasi directory al suo interno. Ad esempio:

cd $PROJECT
$NDK/ndk-gdb

In questo caso, $PROJECT fa riferimento alla directory principale del progetto e $NDK al percorso di installazione di NDK.

Quando richiami ndk-gdb, la sessione viene configurata per cercare i file di origine e le versioni con simboli/debug delle librerie native generate. Dopo essersi collegato correttamente al processo di applicazione, ndk-gdb genera una lunga serie di messaggi di errore, indicando che non riesce a trovare varie librerie di sistema. Questo è normale, perché la macchina host non contiene le versioni simboliche/di debug di queste librerie sul dispositivo di destinazione. Puoi ignorare questi messaggi.

Successivamente, ndk-gdb mostra il solito prompt lldb.

Interagisci con ndk-gdb nello stesso modo in cui interagisci con lldb. Consulta la [mappa dei comandi GDB a LLDB](https://lldb.llvm.org/use/map.html) se non hai dimestichezza con lldb, ma conosci gdb.

ndk-gdb gestisce molte condizioni di errore e mostra un messaggio di errore informativo se viene rilevato un problema. Questi controlli includono l'accertamento del fatto che le seguenti condizioni siano soddisfatte:

  • Verifica che ADB sia nel percorso.
  • Verifica che l'applicazione sia dichiarata come eseguibile in debug nel file manifest.
  • Verifica che sul dispositivo sia possibile eseguire il debug anche dell'applicazione installata con lo stesso nome del pacchetto.

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

Opzioni

Per visualizzare un elenco completo delle opzioni, digita ndk-gdb --help sulla riga di comando. La tabella 1 elenca alcuni dei più utilizzati, insieme a brevi descrizioni.

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

Se avvii 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 Description>
--verbose

Questa opzione indica al sistema di compilazione di stampare informazioni dettagliate sulla configurazione della sessione di debugging nativo. È necessario solo per i 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 viene interrotto se rileva che sullo stesso dispositivo è già in esecuzione un'altra sessione di debug nativa. Questa opzione termina l'altra sessione e la sostituisce con una nuova. Tieni presente che questa opzione non termina l'app di cui viene eseguito il debug, che devi terminare distintamente.
--start

Quando avvii ndk-gdb, per impostazione predefinita tenta di collegarsi a un'istanza esistente in esecuzione della tua app sul dispositivo di destinazione. Puoi ignorare questo comportamento predefinito utilizzando --start per avviare esplicitamente l'applicazione sul dispositivo di destinazione prima della sessione di debug.
--launch=<name>

Questa opzione è simile a --start, tranne per il fatto che ti consente di avviare un'attività specifica dalla tua applicazione. Questa funzionalità è utile solo se il manifest definisce più attività avviabili.
--launch-list

Questa comoda opzione stampa l'elenco di tutti i nomi delle attività avviabili trovati nel manifest dell'app. --start utilizza il nome della prima attività.
--project=<path> Questa opzione specifica la directory del progetto dell'app. È utile se vuoi avviare lo script senza dover prima passare alla directory del progetto.
--port=<port>

Per impostazione predefinita, ndk-gdb utilizza la porta TCP locale 5039 per comunicare con l'app di cui sta eseguendo il debug sul dispositivo di destinazione. L'utilizzo di una porta diversa ti consente di eseguire il debug in modo nativo dei programmi in esecuzione su diversi dispositivi o emulatori connessi alla stessa macchina host.
--adb=<file>

Questa opzione specifica l'eseguibile dello strumento adb. È necessario solo se non hai impostato il percorso in modo da includere l'eseguibile.
  • -d
  • -e
  • -s <serial>
    		•

    Questi flag sono simili ai comandi adb con gli stessi nomi. Imposta questi flag se hai diversi dispositivi o emulatori collegati alla tua macchina host. Ecco il relativo significato:

    -d
    Connettiti a un singolo dispositivo fisico.
    -e
    Connettiti a un singolo dispositivo emulatore.
    -s <serial>
    Connettiti a un dispositivo o un emulatore specifico. Qui, <serial> è il nome del dispositivo elencato dal comando adb devices.

    In alternativa, puoi definire la variabile d'ambiente ADB_SERIAL per elencare un dispositivo specifico, senza la necessità di un'opzione specifica.
  • --exec=<file>
  • -x <file>
    		•

    Questa opzione indica a ndk-gdb di eseguire i comandi di inizializzazione del debugger trovati in <file> dopo la connessione al processo in cui è in corso il debug. Questa è una funzionalità utile se vuoi eseguire ripetutamente un'operazione, ad esempio configurare un elenco di breakpoint, e poi riprendere automaticamente l'esecuzione.
    --nowait

    Disattiva la messa in pausa del codice Java finché il debugger non si connette. Se passi questa opzione, il debugger potrebbe non rilevare i breakpoint iniziali.

    --tui -t

    Attiva l'interfaccia utente di testo, se disponibile.
    --gnumake-flag=<flag>

    Questa opzione è un flag (o più flag) aggiuntivo 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 tre opzioni finali di questa tabella sono solo per la versione di ndk-gdb in Python.