Mobile/Fennec/Android/GDB
Note: the names JimDB and moz-gdb seem to be used interchangeably, meaning the same thing.
Using JimDB (Or, Android GDB with Niceness)
Prebuilt binaries
Linux
Download page
Run 'git pull' inside the utils directory to get the latest GDB utilities.
GDB utilities
A set of tools to make Fennec development on Android easier.
Source and documentation.
Careful of NDK versions
The prebuilt binaries on github are build using an outdated version of the NDK. You should replace the "gdbserver" program by:
[1]
If that still does not work, #mobile on irc.mozilla.org is the place to go.
Building moz-gdb
There are two things to build here: the gdb you'll run on your computer, and the gdbserver you'll install on the device. JimDB's gdb takes care of automatically running /data/local/gdbserver on the device, once it's correctly installed.
Building gdb
Linux
Get required packages:
sudo apt-get install bison flex libncurses5-dev texinfo python2.7-dev
Get source:
git clone git://github.com/darchons/android-gdb.git cd android-gdb git checkout android-gdb_7_4
Run configure and make:
mkdir android-gdb-objdir cd android-gdb-objdir export prefix=/nonexistent /path/to/android-gdb/configure --target=arm-elf-linux --with-python=yes --prefix=$prefix \ --with-gdb-datadir=$prefix/utils --with-system-gdbinit=$prefix/utils/gdbinit make -j4
Reminder: Don't use ~ in the paths you pass here, as Bash wouldn't evaluate it!
The gdb binary will be located at android-gdb-objdir/gdb/gdb
Mac OS X
NOTES:
- BenWa (2012/01/09): It failed to built with clang
- mcomella (2012/07/31): This worked for me, although I had issues when I ran ./configure from the root diretory before running the written commands (I had to "make distclean" after that). I used Lion dev tools.
- jchen (2012/10/17): I ran into a make error about missing python2.7. The cause is a bad config variable in the MacPorts python2.7 port. If I switch to using the native OSX python (by changing PATH), the problem goes away.
Get required packages (unnecessary for OS X 10.8.2; they are include with Mountain Lion):
port install bison flex ncurses texinfo python27
Get source:
git clone git://github.com/darchons/android-gdb.git cd android-gdb git checkout android-gdb_7_4
Run configure and make:
mkdir android-gdb-objdir cd android-gdb-objdir export prefix=/nonexistent /path/to/android-gdb/configure --target=arm-elf-linux --enable-targets=all --with-python=yes --prefix=$prefix \ --with-gdb-datadir=$prefix/utils --with-system-gdbinit=$prefix/utils/gdbinit make -j4
Reminder: Don't use ~ in the paths you pass here, as Bash wouldn't evaluate it!
The gdb binary will be located at android-gdb-objdir/gdb/gdb
Building gdbserver
Linux
Create an NDK toolchain:
cd /PATH/TO/NDK ./build/tools/make-standalone-toolchain.sh
This will tell you that the toolchain was packaged somewhere like /tmp/ndk-username/arm-linux-androideabi-4.4.3.tar.bz2
Extract that toolchain somewhere:
mkdir ~/android-toolchain cd ~/android-toolchain tar -xvf /tmp/ndk-username/arm-linux-androideabi-4.4.3.tar.bz2
Make sure NDK toolchain is in PATH:
export PATH=~/android-toolchain/arm-linux-androideabi-4.4.3/bin:$PATH
Run configure and make for gdbserver:
mkdir android-gdbserver-objdir cd android-gdbserver-objdir /path/to/android-gdb/gdb/gdbserver/configure --host=arm-linux-androideabi \ --with-sysroot=/PATH/TO/NDK/platforms/android-9/arch-arm make -j4
The gdbserver binary will be located at android-gdbserver-objdir/gdbserver.
Reminder: Don't use ~ in the paths you pass here, as Bash wouldn't evaluate it!
Install it on your device:
adb push gdbserver /data/local || adb push gdbserver /data/local/tmp
On some Android models the /data/local is not writable so gdbserver needs to be pushed into /data/local/tmp/
Mac OS X
Setup a toolchain environment for your build, then run configure and make for gdbserver. The android-gdbserver-objdir directory can be anywhere, but creating it within the android-gdb git clone is convenient. The paths below do not necessarily need to be absolute paths, but it will make life easier.
mkdir android-gdbserver-objdir cd android-gdbserver-objdir /ABSOLUTE/PATH/TO/NDK/android-ndk-r5c/build/tools/make-standalone-toolchain.sh --install-dir=android-9-toolchain --platform=android-9 export PATH=android-9-toolchain/bin:$PATH /ABSOLUTE/PATH/TO/GIT/CLONE/android-gdb/gdb/gdbserver/configure --host=arm-linux-androideabi make -j4
The gdbserver binary will be located at android-gdbserver-objdir/gdbserver.
Install it on your device:
adb push gdbserver /data/local | adb push gdbserver /data/local/tmp
Create the moz-gdb directory
Once you've built JimDB, you need to create and populate a moz-gdb directory as explained below.
Indeed, GDB utilities assume the following moz-gdb directory structure:
./bin/
gdb
gdbserver
./utils/
gdbinit
python/
Execute the following commands to create and set up the moz-gdb directory:
mkdir -p moz-gdb/bin cp android-gdb-objdir/gdb/gdb moz-gdb/bin cp android-gdbserver-objdir/gdbserver moz-gdb/bin git clone git://github.com/darchons/android-gdbutils.git moz-gdb/utils
Set up the gdbinit file
Now edit this file:
moz-gdb/utils/gdbinit
and uncomment (remove the #'s) and set the following variables:
python feninit.default.objdir # set it to your fennec object directory python feninit.default.srcroot # set it to your source directory
Linux
Make sure your paths are absolute! The gdbinit file, even though it specifies relative paths by default, will not correctly load debug symbols unless you specify absolute paths.
| INCORRECT | CORRECT |
|---|---|
|
|
|
Running JimDB
Once JimDB is properly set up, with a moz-gdb directory as described above, running Fennec in GDB is very easy:
./moz-gdb/bin/gdb
This will automatically start gdbserver and fennec on the device, and start gdb on your computer.
First run of JimDB
Run JimDB, type as usual 'continue' to actually start running Fennec, give it several seconds, and hit Ctrl+C to interrupt Fennec.
The first time, it will probably complain:
Program received signal SIGINT, Interrupt. warning: Could not load shared library symbols for org.mozilla.fennec_bjacob. Do you need "set solib-search-path" or "set sysroot"?
Do not worry about this. It will seem frozen for several seconds, but let it run. What's happening is that it's pulling all the libraries from the device into the moz-gdb directory. Ignore the suggestion about setting solib-search-path/sysroot, JimDB will do it all for you. Once it's done, you get a GDB invite as usual.
Do this sanity check:
(gdb) info shared
For each loaded library you'll see whether symbols were found: Yes, No, or "Yes (*)" meaning no debug info. Press Enter until the listing is complete. You want to make two things sure:
Ensure that libXUL has debug info i.e. you should see a plain Yes for libxul.so. If not, that means that something is wrong with your fennec build (is it a non-debug build?) or with your gdbinit (see above).
Ensure that no library has a No. Typically, some system libraries and drivers will give you a No. For each such library, you want to manually pull it from the device into moz-gdb/lib/<device hex id>/system/lib. These drivers are typically found in /vendor on your device. Do pull them into system/lib on your computer, as this is where JimDB will find them, even if on the device they are not in /system/lib. Here is an example script to pull all the files in a given directory (here /system/lib) at once:
for file in $(adb shell ls /system/lib | tr "\n" " " | tr "\r" " "); do adb pull /system/lib/$file done
You may have to repeat this for other directories such as /vendor/lib for drivers.
There is one dummy library about which GDB will still report "no":
No org.mozilla.fennec_foobar
Do not worry about that one.
Troubleshooting
- If debug info seems broken (e.g. breakpoints or stepping don't work well), make sure you're using a --disable-optimize --enable-debug build of Fennec. Just --enable-debug doesn't seem to always be enough.