Android Debug Bridge (adb) è uno strumento versatile che ti permette di gestire lo stato di un dispositivo o emulatore.

Alcuni dei modi in cui puoi usare il adb sono:

• Far lampeggiare codice aggiornato in un dispositivo o emulatore, come aggiornamenti di applicazioni o del sistema di Android
• Eseguire comandi di shell su un dispositivo
• Gestire port forwarding su un emulatore o dispositivo
• Copiare files in/da un emulatore o dispositivo

Le sezioni seguenti introducono adb e descrivono molte dei suoi usi comuni.

Contenuti

Panoramica

Emettere comandi adb

Fare una ricerca per istanze dell'emulatore/dispositivo

Direzionare comandi ad una specifica istanza dell'emulatore/dispositivo

Installare un'applicazione

Port forwarding

Copiare Files in e da un istanza di un emulatore/dispositivo

Elenco dei comandi sdb

Emettere comandi di shell

Esaminare databases sqlite3 dalla shell remota

Altri comandi di shell

Attivare logcat logging

Usare comandi di logcat

Filtrare log output

Controllare il formato di logcat output

Visualizzare log buffers alternativi

Visualizzare stdout e stderr

Elenco delle opzioni del comando logcat

Fermare il server adb

Panoramica

Lo strumento adb è un programma client-server che include tre componenti:

• Un client, che gira sul tuo computer. Puoi invocare un client da una shell emettendo un comando adb. Anche altri strumenti di Android come il plugin ADT e il DDMS creano clients adb.
• Un server, che gira come processo di background sul tuo computer. Il server gestisce la comunicazione tra il client e il deamon adb in esecuzione su un emulatore o dispositivo.
• Un daemon, che gira come processo di background su ogni istanza di emulatore o dispositivo.

Quando avvii un client adb, il client prima di tutto controlla se c'è un processo di server adb già in esecuzione. In caso contrario, avvia il processo del server. Quando il server si avvia, si lega alla TCP porta 5037 locale e attende i comandi inviati dal client adb -- tutti i clients adb usano la porta 5037 per comunicare con il server adb.

Il server configura poi connessioni con tutte le istanze dell'emulatore/dispositivo. Localizza le istanze dell'emulatore/dispositivo facendo una scansione delle porte con numeri dispari all'interno dell'intervallo da 5555 a 5585, l'intervallo usato dall'emulatore/dispositivo. Nel punto in cui il server trova un deamon adb, configura una connessione con quella porta. Nota che ogni istanza dell'emulatore/dispositivo acquisisce un paio di porte sequenziali -- una porta con numero pari per connessioni di console e una porta con numero dispari per connessioni adb. Per esempio:

Emulatore 1, console: 5554
Emulatore 1, adb: 5555
Emulatore 2, console: 5556
Emulatore 2, adb: 5557 ...

Come mostrato dall'esempio sopra, l'istanza dell'emulatore connessa ad adb sulla porta 5555 è la stessa istanza la cui console comunica con la porta 5554.

Una volta che il server ha configurato le connessioni con le istanze dell'emulatore, puoi usare i comandi adb per controllare ed accedere a quelle istanze. Dato che il server gestisce connessioni con l'emulatore/dispositivo e gestisce i comandi per clients adb multipli, puoi controllare qualsiasi istanza di emulatore/dispositivo da qualsiasi client (o da uno script).

Le sezioni seguenti descrivono i comandi che puoi usare per accedere alle funzionalità di adb e gestire lo stato di un emulatore/dispositivo. Nota che se stai sviluppando applicazioni Android in Eclipse e hai installato il plugin ADT, non hai bisogno di accedere all'adb dalla finestra terminale. Il plugin ADT fornisce un'integrazione trasparente di adb nell'IDE Eclipse. Tuttavia, puoi comunque usare l'adb direttamente se necessario, come per operazioni di debugging.

Emettere comandi adb

Puoi emettere comandi adb da un terminale sul tuo computer per lo sviluppo o da uno script. La sintassi è:

adb [-d {<ID>|<serialNumber>}] <command>

Quando emetti un comando, il programma invoca un client adb. Il client non è specificatamente associato a un'istanza di un emulatore, quindi se sono in esecuzione emulatori/dispositivi multipli, devi usare l'opzione -d per specificare l'istanza obiettivo a cui il comando dovrebbe essere diretto. Per ulteriori informazioni sull'utilizzo di questa opzione, consulta Direzionare comandi ad una specifica istanza dell'emulatore/dispositivo.

Fare una ricerca per istanze dell'emulatore/dispositivo

Prima di emettere comandi adb, è utile sapere quali istanze di emulatore/dispositivo sono connesse al server adb. Puoi generare una lista di emulatori/dispositivi collegati  usando il comando devices:

adb devices

In risposta, adb stampa questo informazioni di status per ogni istanza:

• ID — Un identifier assegnato da adb per istanze consecutive man mano che vengono lanciate (adb assegna ID 1 alla prima istanza lanciata).
• Numero di serie (Serial number) — Una stringa creata da adb per identificare esclusivamente un'istanza di un emulatore/dispositivo su una porta specifica.
• Stato — Lo stato di connessione dell'istanza. Sono supportati tre stati:
  • device — l'istanza è connessa al sever adb.
  • offline — l'istanza non è connesa o non risponde.
  • bootloader — il bootloader è in esecuzione.
• Lock — Stato bloccato (Locked) dell'istanza. 0 significa sbloccato (not locked).

L'output per ogni istanza è formattata in questo modo:

[ID] [serialNumber] [state] [lock]

Questo è un esempio che mostra il comando devices e il suo output:

$ adb devices
List of devices attached 
1  emulator-tcp-5555  device  0
2  emulator-tcp-5557  device  0
3  emulator-tcp-5559  device  0

Se non c'è alcun emulatore/dispositivo in esecuzione, adb risponde con no device.

Direzionare comandi ad una specifica istanza dell'emulatore/dispositivo

Sono in esecuzione istanze multiple di emulatori/dispositivi, devi specificare una istanza obiettivo quando emetti un comando. Pe far ciò, usa l'opzione  -d nei comandi. La sintassi per l'opzione -d è:

adb -d {<ID>|<serialNumber>} <command>

Come mostrato dall'esempio sopra, specifichi l'istanza obiettivo per un comando usando il suo numero di serie assegnato da adb. Puoi usare il comando devices per ottenere i numeri di serie di istanze in esecuzione.

Ecco due esempi:

adb -d 2 install helloWorld.apk

adb -d emulator-tcp-5557 install helloWorld.apk

Nota che, se emetti un comando senza specificare un'istanza obiettivo per esso, adb di default invia il comando all'istanza alla porta 5555, se un'istanza è connessa a quella porta. 

Installare un'applicazione

Puoi usare adb per copiare un'applicazione dal tuo computer per lo sviluppo e installarla su un'istanza di un emulatore/dispositivo. Per far ciò, usa il comando install, devi anche specificare però il percorso al fine .apk che vuoi installare:

adb install <path_to_apk>

Per ulteriori informazioni su come creare un file .apk da installare su un'istanza di un emulatore/dispositivo, consulta Android Asset Packaging Tool (aapt).

Nota che, se stai usando l'IDE Eclipse e hai installato il plugin ADT, non hai bisogno di usare adb (o aapt) direttamente per installare la tua applicazione sull'emulatore/dispositivo. E' il plugin ADT che gestisce il packaging e l'installazione dell'applicazione al posto tuo.

Port forwarding

Puoi usare il comando forward per configurare un arbitrario port forwarding — inoltro di richieste su uno specifico host port ad una porta differente su un'istanza di un emulatore/dispositivo. Di seguito viene mostrato come dovresti fare per configurare il forwarding di host port 6100 alla porta 7100 dell'emulatore/dispositivo:

adb forward tcp:6100 tcp:7100

Puoi anche usare adb per configurare un forwarding verso un "abstract" domain sockets di Unix, come illustrato di seguito:

adb forward tcp:6100 local:logd

Copiare Files in e da un istanza di un emulatore/dispositivo

Puoi usare i comandi adb pull e push per copiare files in e da un files di dati di un'istanza di emulatore/dispositivo. Di versamente dal comando install, che copia solo un file .apk in una posizione specifica, i comandi pull e push ti permettono di copiare files e directories arbitrari in qualsiasi posizione in un'istanza di emulatore/dispositivo.

Per copiare un file o una directory (ricorsivamente) dall'emulatore o dispositivo, usa

adb pull <remote> <local>

Per copiare un file o una directory (ricorsivamente) nell'emulatore o dispositivo, usa

adb push <local> <remote>

Nei comandi, <local> e <remote> si riferiscono al percorso verso il file/directory obiettivo dell'operazione sul tuo computer per lo sviluppo (local) e sull'istanza di emulatore/dispositivo (remote).

Ecco un esempio:

adb push foo.txt /tmp/foo.txt

Elenco dei comandi sdb

La seguente tabella elenca tutti i comandi adb supportati e spiega il loro significato e utilizzo.

Emettere comandi di shell

Puoi usare il comando shell per emettere comandi di shell remota in un'istanza di un emulatore/dispositivo. Puoi emettere un comando di shell singolo senza inserire una shell remota, oppure puoi semplicemente scendere in una shell remota da cui puoi navigare e emettere comandi UNIX.

Per emettere un comando di shell singolo senza inserire una shell remota, usa il comando shell in questo modo:

adb [-d {<ID>|<serialNumber>}] shell <shellCommand>

Per scendere in una shell remota in un'istanza di un emulatore/dispositivo, usa il comando shell in questo modo:

adb [-d {<ID>|<serialNumber>}] shell

Quando sei pronto ad uscire dalla shell remota, usa CTRL+D o exit per porre fine alla sessione shell.

Le sezioni seguenti forniscono ulteriori informazioni sui comandi di shell che puoi usare.

Esaminare databases sqlite3 dalla shell remota

Per una shell remota adb, puoi usare il programma command-line sqlite3 per gestire databases SQLite create da applicazioni Android. Lo strumento sqlite3 include molti comandi utili, come .dump per stampare i contenuti di una tabella e .schema per stampare lo statement SQL CREATE per una tabella esistente. Questo strumento ti dà anche la capacità di eseguire comandi SQLite al volo.

Per usare sqlite3, entra in una shell remota nell'istanza dell'emulatore, come descritto sopra, poi invoca lo strumento usando il comando sqlite3. Facoltativamente,  quando invochi sqlite3 puoi specificare il percorso completo per il database che vuoi esplorare. Le istanze di un emulatore/dispositivo, immagazzinano i databases SQLite3 nella cartella /data/data/<package_name>/databases/.

Ecco un esempio:

$ adb -d emulator-tcp-5557 shell
# sqlite3 /data/data/com.example.google.rss.rssexample/databases/rssitems.db
SQLite version 3.3.12
Enter ".help" for instructions
.... enter commands, then quit...
sqlite> .exit

Una volta invocato sqlite3, puoi emettere i comandi sqlite3 nella shell. Per uscire e ritornare alla shell remota adb, usa exit o CTRL+D.

Altri comandi di shell

Attivare logcat logging

Il sistema di logging di Android fornisce un meccanismo per raccogliere e visualizzare output di debug del sistema. Logs da varie applicazioni e porzioni del sistema vengono raccolti in una serie di buffers circolari, che possono poi essere visualizzati e filtrati dal comando logcat. 

Usare comandi di logcat

Puoi usare il comando logcat per visualizzare e seguire i contenuti dei buffers di log del sistema. L'uso generale è:

[adb] logcat [<option>] ... [<filter-spec>] ...

Le sezioni seguenti spiegano la specificazione di filtri e le opzioni dei comandi. Vedi Elenco delle opzioni del comando logcat per un riassunto di queste opzioni.

Puoi usare il comando logcat dal tuo computer per lo sviluppo o da una shell remota adb in un'istanza di emulatore/dispositivo. Per visualizzare output di log sul tuo computer, usa

$ adb logcat

e da una shell remota adb usa

# logcat

Filtrare log output

Ogni messaggio di log di Android ha un tag e priority (priorità) associati ad esso.

• Il tag di un messaggio di log è una breve stringa che indica i componenti del sistema dai quali viene originato il messaggio (per esempio, "View" per il sistema di visualizzazione).
• La priorità è costituita da uno dei seguenti valori di carattere seguenti, ordinati dalla priorità più bassa alla più alta:
  • V — Verbose (priorità più bassa)
  • D — Debug
  • I — Info
  • W — Warning
  • E — Error
  • F — Fatal
  • S — Silent (priorità più alta, in cui non viene mai stampato nulla)

Puoi ottenere una lista di tags usati nel sistema, con le priorità, eseguendo logcat e osservando le prime due colonne di ogni messaggio, date come <priority>/<tag>.

Questo è un esempio di output di log che mostra che il messaggio si riferisce ad un livello di priorità "I" e al tag "ActivityManager":

I/ActivityManager(  585): Starting activity: Intent { action=android.intent.action...}

Per ridurre l'output di log ad un livello gestibile, puoi restringerlo usando filter expressions. Filter expressions ti permettono di indicare al sistema la combinazione di tags-priority che ti interessa — il sistema sopprime altri messaggi per i tags specificati.

Una filter expression segue questo formato tag:priority ..., dove tag indica il tag di interesse e priority indica il livello minimo di priorità riportato per quel tag. I messaggi per quel tag da o sopra quella priorità specificata sono scritti sul log. Puoi fornire qualsiasi numero di specificazioni tag:priority in una filter expression singola. La serie di specificazioni è delimitata da spazi bianchi.

Questo è un esempio di una filter expression che sopprime tutti i messaggi di log eccetto quelli con il tag "ActivityManager", con priorità "Info" o superiore, e tutti i messaggi di log con il tag "MyApp", con priorità "Debug" o superiore:

adb logcat ActivityManager:I MyApp:D *:S

L'elemento finale nell'espressione sopra, *:S, imposta il livello di priorità per tutti i tag a "silent", assicurando così che vengano mostrati solo i messaggi di log con "View" e "MyApp". Usare *:S è un ottimo modo per assicurarsi che l'output di log sia ristretto in base ai filtri che hai specifcato esplicitamente -- permette ai tuoi filtri di fungere da "whitelist" per l'output di log.

La filter expression seguente mostra tutti i messaggi di log con livello di priorità "warning" e superiore, su tutti i tag:

adb logcat *:W

Se stai eseguendo logcat dal tuo computer per lo sviluppo (rispetto ad eseguirlo su una shell remota adb), puoi anche impostare una filter expression di default esportando un valore dalla variabile dell'ambiente ANDROID_LOG_TAGS:

export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"

Nota che il filtro ANDROID_LOG_TAGS non viene esportato nell'istanza di un emulatore/dispositivo, se stai eseguendo logcat da una shell remota o usando adb shell logcat.

Controllare il formato di logcat output

I messaggi di log contengono un certo numero di campi di metadati (metadata field), oltre che al tag e alla priorità. Puoi modificare il formato dell'output per i messaggi in modo che mostrino uno specifico campo di metadati. Per far ciò, usa l'opzione -v e specifica uno dei formati dell'output supportati elencati qui di seguito.

• brief — Mostra priorità/tag e PID del processo originante (il formato di default).
• process — Mostra solo il PID.
• tag — Mostra solo priorità/tag.
• thread — Mostra solo process:thread e priorità/tag.
• raw — Mostra il messaggio di log grezzo, senza altri campi di metadati.
• time — Mostra la data, momento di invocazione, priorità/tag e PID del processo originante.
• long — Mostra tutti i campi di metadati e separa i messaggi con una linea vuota.

Quando avvii logcat, puoi specificare il formato dell'output che vuoi usare attraverso l'opzione -v:

[adb] logcat [-v <format>]

Questo esempio mostra come generare messaggi nel formato di output thread:

adb logcat -v thread

Nota che puoi specifcare solo un formato con l'opzione -v.

Visualizzare log buffers alternativi

Il sistema di logging di Android mantiene buffers circolari multipli per messaggi di log, e non tutti i messaggi di log sono inviati al buffer circolare di default. Quindi per vedere altri messaggi di log, puoi avviare logcat con l'opzione -b, per richiedere la visualizzazione di un buffer circolare alternativo. Puoi visualizzare i buffers alternativi seguenti:

• radio — Visualizza il buffer che contiene messaggi relativi a radio/telephony.
• events — Visualizza il buffer che contiene messaggi relativi a eventi.
• main — Visualizza il buffer di log principale (default)

L'uso dell'opzione -b è:

[adb] logcat [-b <buffer>]

Questo è un esempio di come visualizzare un buffer che contiene messaggi radio e di telefonia:

adb logcat -b radio

Visualizzare stdout e stderr

Di default, il sistema di Android invia output stdout e stderr (System.out e System.err) a /dev/null. In processi che girano sulla VM Dalvik, puoi fare in modo che il sistema scriva una copia dell'output del file di log. In questo caso, il sistema scrive i messaggi al log usando i tags di log stdout e stderr, entrambi con priorità I.

Per convogliare l'output in questa maniera, devi fermare un'istanza di un emulatore/dispositivo in esecuzione e usare poi il comando di shell setprop per attivare il reindirizzamento di output:

$ adb shell stop
$ adb shell setprop log.redirect-stdio true
$ adb shell start

Il sistema conserva questa impostazione fino a quando non posi fine all'istanza dell'emulatore/dispositivo. Per usare l'ipostazione come default sull'istanza dell'emulatore/dispositivo, puoi aggiungere una voce a /data/local.prop sul dispositivo.

Elenco delle opzioni del comando logcat

Fermare il server adb

In alcuni casi, potresti avere bisogno di terminare il processo server adb e di riavviarlo. Per esempio, se adb non risponde a un comando, puoi terminare il server e riavviarlo, operazione che potrebbe risolvere il problema.

Per fermare il server adb, usa kill-server. Puoi poi riavviare il server emettendo qualsiasi comando adb.