This page details using LLDB or GDB for OS development. For app development, see Debug your app instead, which explains how to use the Android Studio GUI (based on LLDB).
GDB is deprecated and will be removed soon. If you're switching from GDB to LLDB, you should probably start by reading the LLDB Tutorial. If you're an expert GDB user, the GDB to LLDB command map is very helpful while transitioning.
Prerequisites
To use a debugger:
- Set up the build environment with the usual
envsetup.sh
command. - Run the same
lunch
command you used when building.
For more help with setting up your environment, see Set up environment.
Debugging running apps or processes
To connect to a running app or native daemon, use
gdbclient.py
with a PID. For example, to debug the process with PID
1234, run this on the host:
gdbclient.py -p 1234
The script sets up port forwarding, starts the appropriate remote debugging stub on the device, starts the debugger on the host, configures it to find symbols, and connects it to the remote debugging stub.
Debugging native process startup
To debug a process as it starts, use gdbclient.py
with the -r
option. For example, to debug ls /bin
, run this on the host:
gdbclient.py -r /system/bin/ls /bin
Then, enter continue
at the debugger's prompt.
Debugging app startup
Sometimes you want to debug an app as it starts, such as when there's a crash
and you want to step through code to see what happened before the crash.
Attaching works in some cases, but in other cases is
impossible because the app crashes before you can attach. The
logwrapper
approach (used for strace
)
doesn't always work because the app might not have
permissions to open a port, and gdbserver
inherits that
restriction.
To debug app startup, use the developer options in Settings to instruct the app to wait for a Java debugger to attach:
- Go to Settings > Developer options > Select debug app and choose your app from the list, then click Wait for debugger.
- Start the app, either from the launcher or by using the command line to run:
adb shell am start -a android.intent.action.MAIN -n APP_NAME/.APP_ACTIVITY
- Wait for the app to load and a dialog to appear telling you the app is waiting for a debugger.
- Attach
gdbserver
/gdbclient
normally, set breakpoints, then continue the process.
To let the app run, attach a Java Debug Wire Protocol (JDWP) debugger such as Java Debugger (jdb):
adb forward tcp:12345 jdwp:XXX # (Where XXX is the PID of the debugged process.)
jdb -attach localhost:12345
Debugging apps or processes that crash
If you want debuggerd
to suspend crashed processes so that you can
attach a debugger, set the appropriate property:
- After Android 11
adb shell setprop debug.debuggerd.wait_for_debugger true
- Android 11 and lower
adb shell setprop debug.debuggerd.wait_for_gdb true
- Android 6.0 Marshmallow and lower
adb shell setprop debug.db.uid 999999
At the end of the usual crash output, debuggerd
provides copy and paste
instructions in logcat showing how to connect the debugger to the crashed process.
Debugging without symbols
For 32-bit ARM, if you don’t have symbols, gdb
can't determine
which instruction set it's disassembling (ARM or Thumb). To specify the
instruction set chosen as the default when symbol information is missing, set
the following property:
set arm fallback-mode arm # or thumb
Debugging with VS Code
LLDB supports debugging platform code on Visual Studio Code. You can use the VS Code debugger frontend instead of the LLDB CLI interface to control and debug native code running on devices.
Before using VS Code for debugging, install the CodeLLDB extension.
To debug code using VS Code:
- Ensure that all build artifacts (such as symbols) required to run
gdbclient.py
orlldbclient.py
are present. - Run the following command:
lldbclient.py --setup-forwarding vscode-lldb ANY_OTHER_FLAGS -p pid | -n proc-name | -r ...
This prints a JSON object and
lldbclient.py
continues running. This is expected; don't kill thelldbclient.py
program.The
-r
flag must be the last flag if it is present due to how flags are parsed by the tool. - In the debugging tab in VS Code, select add configuration, then select
LLDB: Custom Launch.
This opens a
launch.json
file and adds a new JSON object to a list. - Delete the newly added debugger configuration.
- Copy the JSON object printed by
lldbclient.py
and paste it into the object you just deleted. Save the changes. - To reload the window to refresh the debugger list, press
Ctrl+Shift+P and type
reload window
. - Select the new debugger configuration and press run. The debugger should connect after 10 to 30 seconds.
- When you're done debugging, go to the terminal running
lldbclient.py
and press Enter to end thelldbclient.py
program.