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.

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:

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
python feninit.default.objdir = '~/Source/mozilla-android/obj-android' python feninit.default.srcroot = '~/Source/mozilla-central/mozilla'	python feninit.default.objdir = '/home/USERNAME/Source/mozilla-android/obj-android' python feninit.default.srcroot = '/home/USERNAME/Source/mozilla-central/mozilla'

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.