This guide provides basic recommendations for using ndk-gdb to debug native mobile VR projects, and is intended to supplement the relevant Android Studio documentation.
The Android NDK includes a powerful debugging tool called ndk-gdb, a small shell script wrapped around GDB. Using ndk-gdb from the command line adds convenient features to your debugging workflow by allowing, for example, adding breakpoints, stepping through code, and inspecting variables.
Break On Function
(gdb) break SomeFunctionName()
or
(gdb) break SomeClass::SomeMethod()
Example usage:
(gdb) break OVR::VrCubeWorld::Frame(OVR::VrFrame const&) Breakpoint 2 at 0xf3f56118: file jni/../../../Src/VrCubeWorld_Framework.cpp, line 292.
Break On File:Line
(gdb) break SomeFile.cpp:256
Conditional Breakpoints
Add if <some condition> to the end of your break command.
Example usage:
(gdb) break OVR::VrCubeWorld::Frame(OVR::VrFrame const&) if vrFrame.PredictedDisplayTimeInSeconds > 24250.0 Breakpoint 6 at 0xf3f58118: file jni/../../../Src/VrCubeWorld_Framework.cpp, line 292.
Break At Current Execution
Example usage:
(gdb) break OVR::VrCubeWorld::Frame(OVR::VrFrame const&) if vrFrame.PredictedDisplayTimeInSeconds > 24250.0 Breakpoint 6 at 0xf3f58118: file jni/../../../Src/VrCubeWorld_Framework.cpp, line 292.
Break At Current Execution
When an application is actively running, press control-c to break immediately and bring up the gdb prompt.
Step Over
(gdb) next
or
(gdb) n
Step Into
(gdb) step
or
(gdb) s
Continue Execution
(gdb) continue
or
(gdb) c
Print Struct
You may enable pretty printing mode to add new lines between struct elements (optional):
(gdb) set print pretty on
To print the struct:
(gdb) print SomeStructVariable
Example usage:
(gdb) print currentRotation $1 = { x = 23185.9961, y = 23185.9961, z = 0, static ZERO = { x = 0, y = 0, z = 0, static ZERO = <same as static member of an already seen type> } }
printf
Example usage:
(gdb) printf "x = %f\n", currentRotation.x x = 23185.996094
GDB breakpoints may be set to automatically execute arbitrary commands upon being hit. This feature is useful for inserting print statements into your code without recompiling or even modifying data at key points in your program without halting execution entirely. It is controlled by the commands command.
You may specify the breakpoint number with an optional single argument; if omitted, the final breakpoint is used. You are then presented with a series of lines beginning with > where you may enter GDB commands (one per line) that will be executed upon hitting the breakpoint, until the command sequence is terminated with end.
In the following example, we create a breakpoint automatically prints the value of a local variable and then continues execution, upon being hit:
(gdb) break OVR::VrCubeWorld::Frame(OVR::VrFrame const&) Breakpoint 1 at 0xf3f56118: file jni/../../../Src/VrCubeWorld_Framework.cpp, line 292. (gdb) commands Type commands for breakpoint(s) 1, one per line. End with a line saying just "end". >silent >printf "time = %f\n", vrFrame.PredictedDisplayTimeInSeconds >continue >end
To enable or disable the TUI, press CTRL+x followed by CTRL+a.
For more information on TUI keyboard shortcuts, see https://sourceware.org/gdb/onlinedocs/gdb/TUI-Keys.html.