NoteJimDB is a fork of GDB used for simplifying Fennec development. It consists of two parts: * Binaries - the names JimDB and mozGDB/GDBServer binaries that include Android-specific patches (https://github.com/darchons/android-gdb seem )* Scripts - the Python scripts that run under GDB to be used interchangeably, meaning the same thingsimplify common tasks (https://github.com/darchons/android-gdbutils)Use #mobile on IRC for support.
= Using JimDB (Or, Android GDB with Niceness) === Prebuilt binaries =Getting started =
=== Linux =Using pre-built binaries ==
[https://github.com/darchons/android-gdb/downloads Download page]=== Instructions ===
# Download the latest pre-built binaries for your platform from [http://people.mozilla.org/~nchen/jimdb this directory]# Extract to a user-writable directory# Run 'git pull' from inside the utils / directory to get the latest GDB utilities.scripts# Launch bin/gdb to start using JimDB!
=== GDB utilities Example ===
A set of tools to make Fennec development on Android easierFor Linux, cd $HOME wget http://people.mozilla.org/~nchen/jimdb/jimdb-linux-x64.tar.bz2 # step 1 tar -xf jimdb-linux-x64.tar.bz2 # step 2 cd jimdb/utils # step 3 git pull ../bin/gdb # step 4
[http://github.com/darchons/android== Custom-gdbutils Source and documentation].building ==
=== Careful of NDK versions Step 1. Compiling the binaries ===
The prebuilt binaries on github are build using an outdated version of the NDK. You should replace the "gdbserver" program by: [http://people.mozilla.org/~nchen/gdbserver.tar.bz2] 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===== GDB =====
Make sure NDK toolchain is in PATH# Get a zip of the source from [https: export PATH=~//github.com/darchons/android-toolchaingdb the GitHub repo] (Get the zip because cloning takes a lot longer)# Extract the zip# You may need to install additional packages in order to build GDB. For example,<pre>sudo apt-get build-dep gdb</pre># Run configure inside the source directory<pre>./configure --target=arm-elf-linux-androideabiandroid --with-python=yes -4.4.3-prefix=/nonexistent \ --with-gdb-datadir=/nonexistent/utils --with-system-gdbinit=/nonexistent/utils/gdbinit</pre># Run make <pre>make -j8</pre># The compiled binary will be at gdb/bin:$PATHgdb
Run configure and make for gdbserver (gdbserver comes with the android-gdb repository your checked out earlier): cd android-gdb 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=== GDBServer =====
The Consider using the pre-built gdbserver binary will be located at from the "Using pre-built binaries" section above; gdbserver is not specific to your platform. Otherwise,# Use the source directory from above# Make sure you have a copy of the Android NDK# Run configure inside the ''gdb/gdbserver directory''(following is for NDK r8d)<pre>export NDK=/PATH/TO/NDK export PATH=$PATH:$NDK/toolchains/arm-linux-androideabi-4.6/prebuilt/linux-x86/bin ./configure --host=arm-linux-androideabi --with-sysroot=$NDK/platforms/android-gdbserver9/arch-arm</pre># Run make <pre>make -objdirj8</pre># The compiled binary will be at gdbserver''.
Reminder: Don't use ~ in the paths you pass here, as Bash wouldn't evaluate it!==== Mac ====
==== Mac OS X = GDB =====
Setup # Get a toolchain environment for your zip of the source from [https://github.com/darchons/android-gdb the GitHub repo] (Get the zip because cloning takes a lot longer)# Extract the zip# You may need to install additional packages in order to buildGDB. For example, then run <pre>port install bison flex ncurses texinfo python27</pre># Run configure and make for gdbserverinside the source directory<pre>. The /configure --target=arm-elf-linux-android-gdbserver-objdir directory can be anywhere, but creating it within the androidwith-python=yes --prefix=/nonexistent \ --with-gdb git clone is convenient. -datadir=/nonexistent/utils --with-system-gdbinit=/nonexistent/utils/gdbinit</pre># Run make <pre>make -j8</pre># The paths below do not necessarily need to compiled binary will be absolute paths, but it will make life easier.at gdb/gdb
Run configure and make for gdbserver (gdbserver comes with the android-gdb repository your checked out earlier): cd android-gdb 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= GDBServer =====
The Consider using the pre-built gdbserver binary will be located at from the "Using pre-built binaries" section above; gdbserver is not specific to your platform. Otherwise,# Use the source directory from above# Make sure you have a copy of the Android NDK# Run configure inside the ''gdb/gdbserver directory''(following is for NDK r8d)<pre>export NDK=/PATH/TO/NDK export PATH=$PATH:$NDK/toolchains/arm-linux-androideabi-4.6/prebuilt/linux-x86/bin ./configure --host=arm-linux-androideabi --with-sysroot=$NDK/platforms/android-9/arch-arm</pre># Run make <pre>make -j8</pre># The compiled binary will be at gdb/gdbserver-objdir/gdbserver''.
=== Create the moz-gdb Step 2. Creating JimDB directory ===
Once you've built To get the most out of JimDB, in addition to the binaries, you need to create and populate a moz-gdb directory as explained belowthe Python scripts. IndeedBut first, GDB utilities the scripts assume you have the following moz-gdb JimDB directory structure:,
./bin/
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 #Therefore, you's) and set the following variables: python feninit.default.objdir # set it d need 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.<table style="border: 1px solid black;"><tr><th style="background: rgb(250,35,35); color: black; font-weight: bold;">INCORRECT</th><th style="background: rgb(35,250,35); color: black; font-weight: bold;">CORRECT</th></tr><tr><td><code>python feninit.default.objdir = '~/Source/mozilla-android/obj-android'python feninit.default.srcroot = '~/Source/mozilla-central/mozilla'</code></td><td><code>python feninit.default.objdir = '/home/USERNAME/Source/mozilla-android/obj-android'python feninit.default.srcroot = '/home/USERNAME/Source/mozilla-central/mozilla'</code></td></tr></table> == Running a JimDB ==directory Once JimDB is properly set up, with a moz-# Copy gdb directory as described and gdbserver from steps above, running Fennec in GDB is very easy: ./moz-gdb/to bin/gdb This will automatically start gdbserver and fennec on # Clone the device, and start gdb on your computer. === First run of JimDB ===Python scripts to utils/# 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-pathbin/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 libxulFor example, mkdir -p jimdb/bin # step 1 cp /PATH/TO/SOURCE/gdb/gdb jimdb/bin # step 2 cp /PATH/TO/SOURCE/gdb/gdbserver/gdbserver jimdb/bin git clone git://github.so. If not, that means that something is wrong with your fennec build (is it a noncom/darchons/android-debug build?) or with your gdbinit (see above)gdbutils.git jimdb/utils # step 3 jimdb/bin/gdb # step 4
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 = Using 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== FAQ ==
You may have === What is moz-gdb?* moz-gdb was a synonym for JimDB, but it's no longer used, to repeat this for other directories such as /vendor/lib for drivers.avoid confusion
=== "configure: error: failure running python-config" when compiling GDB ===
* python may point to python3 on your machine. You need to specify where python2 is by using, for example, --with-python=python2 in your configure line
There is one dummy library about which GDB will still report === "noerror while loading shared libraries: libtinfo.so.5":on Linux ===* You may need to create a libtinfo.so.5 symlink to libncurses.so.5. For example, sudo ln -s libncurses.so.5 /usr/lib/libtinfo.so.5
No org.mozilla.fennec_foobar=== "cannot locate symbol "__exidx_end"" when starting to debug ===* If you're using pre-built binaries, you need to update to a newer version of JimDB* If you're using custom-built binaries, you need to recompile gdbserver using a newer version of the NDK
Do not worry about that one=== GDB crashed and Fennec is stuck.Halp!! ===* GDBServer may still be attached to Fennec but is unable to communicate with GDB; try killing GDBServer adb shell run-as org.mozilla.fennec_$USER kill `adb shell ps | grep gdb | awk '{print $2}'`
=== Troubleshooting JimDB sucks! Halp!! ===* Come on #mobile on IRC* Or file a bug under Firefox for Android, JimDB component
* If debug info seems broken (e.g. breakpoints or stepping don't work well), make sure === JimDB is awesome now!! Can I buy you're using a --disable-optimize --enable-debug build of Fennec. Just --enable-debug doesn't seem to always be enough.$beverage? ===* Yes
