ADB (Android Debug Bridge) is an essential tool provided by the Android SDK that makes it possible to push and pull data from either a real device or a virtual device, as well as view logs and crash data.
This document won’t explain every facet of ADB (look here for that), but I will go over the commands that I’ve found most useful over the last year and change that I’ve been using the system for game development.
ADB runs on the command line (Windows) or terminal (Linux/Mac/Cygwin). To ensure ADB is available for you to use simply type adb into the terminal. You will get help output if adb is available, and “command not found” if it isn’t found. ADB is a tool provided by the Android SDK at “android-sdk/platform-tools”. My last post discussed how you could add this folder to your path, which will make the command available anywhere.
ADB runs a “daemon” (a sort of server) in the background. This isn’t something you need to really worry about – if you try to do something with ADB and the server isn’t running, it will start up for you. However, if you ever need to restart ADB, you can issue the adb kill-server command, followed by adb start-server.
As a final note, on Windows, I’d suggest using Cygwin over the Command Line for controlling ADB, simply because the terminal provided by Cygwin is more feature-rich.
See Available Devices
Simply type abd devices to see all the devices connected to the system. Devices are identified by a serial number of sorts – unfortunately, I haven’t found a way to change this to more meaningful names. This command will list both real and virtual devices.
Most of the other commands you can issue in ADB require that you have at least one device attached to the system. I usually only have one device connected to the system because most ADB commands will choose a device to use if more than one is present, and I like to know which one that is.
Installing and Uninstalling APKs
At some point, you’ll have an APK for your app, and you’ll need to put that APK on a device (unless Eclipse does it for you). Luckily, this is quite easy.
To install an APK, simply type adb install my_app.apk.
If you have a version of the app on the device already, and you run the install command, you’ll receive an INSTALL_FAILED_ALREADY_EXISTS error. You need to specify “-r”, which tells adb to reinstall/upgrade your app, like so: adb install -r my_upgraded_app.apk. In a testing environment, this is the closest action you can take to simulating an app upgrade on the marketplace (say, from v1.1 to v1.2). All save data is preserved, just the app is replaced.
To uninstall an app from the device use adb uninstall <bundleID>. Your bundle ID uniquely identifies your app, so an example would be adb uninstall com.mycompany.myapp. You can specify “-k” to keep data after the uninstall.
Viewing the Device Log
Viewing the device log is easily done by specifying the adb logcat command. This will output log info from the connected device in real time. Simple as that! Just hit ctrl+c to stop output.
While debugging, the log can print a lot of crap you don’t care about; use the “-s” switch to filter for specific app output. For example, adb logcat -s Unity will only output stuff related to a Unity app. A danger to filtering is that you might miss important data output by another program that is actually related to a bug you are hunting.
Pushing/Pulling Data From the Device
You can push/pull any sort of data to/from the device if it is helpful.
You push data like so: adb push <sourceDir> <destDir>. The destination directory should be on the device. adb pull works the same way, except the destination directory should be on your machine.
I don’t use this too often, but a good example of it’s potential benefit is to get “tombstones” off the device – essentially, crash reports that are located in the “tombstones” directory on the device. It can also be used to root some devices, which gives you access to more of the internal workings of the device.
Navigating the Device’s Folder Structure
You can navigate the device’s folder structure much like you navigate your own system via the Terminal. Simply execute adb shell to gain access to the device in this way. You can then use common Linux terminal commands (ls, cd, rm, etc) to take a look at the device’s internal file structure and modify things.
You will have a pretty simple time getting around a virtual device’s folder structure (which is very educational), but real devices tend to be a bit difficult to break into. For security reasons, a lot of devices will deny you access to the “data” folder on a device, which is where private app data is stored. To access this data, you need to “root” your phone. Unfortunately, there is no single solution to doing this – it varies from device to device. However, searching the net will undoubtedly yield plenty of forum threads chronicling people’s successes and failures at rooting their phones.
You can also issue single commands to the shell by executing adb shell <command>. This can be useful when you want to navigate the shell from an automated script, for example.
There are a few additional ADB commands available, which you can read about by typing just adb by itself. However, I have had little reason to use more than the above commands, and 90% of the time I just use install, uninstall, devices and logcat. Those four give you most of the info and power you need to get your apps on devices and test them out.