|
|
Line 1: |
Line 1: |
| Note: the names JimDB and moz-gdb seem to be used interchangeably, meaning the same thing.
| | JimDB is a fork of GDB used for simplifying Fennec development. It consists of two parts: |
| | * Binaries - the GDB/GDBServer binaries that include Android-specific patches (https://github.com/darchons/android-gdb) |
| | * Scripts - the Python scripts that run under GDB to simplify common tasks (https://github.com/darchons/android-gdbutils) |
| | Use #mobile on IRC for support. |
|
| |
|
| = Using JimDB (Or, Android GDB with Niceness) = | | = Getting started = |
| == Prebuilt binaries ==
| |
|
| |
|
| === Linux === | | == Using pre-built binaries == |
|
| |
|
| [https://github.com/darchons/android-gdb/downloads Download page]
| | === Instructions === |
|
| |
|
| Run 'git pull' inside the utils directory to get the latest GDB utilities. | | # 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 scripts |
| | # Launch bin/gdb to start using JimDB! |
|
| |
|
| === GDB utilities === | | === Example === |
|
| |
|
| A set of tools to make Fennec development on Android easier.
| | For 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-gdbutils Source and documentation].
| | == Custom-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:
| | There are two things to build here: gdb and gdbserver |
| | |
| [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 ==== | | ==== Linux ==== |
|
| |
|
| Create an NDK toolchain:
| | ===== GDB ===== |
| 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:
| | # Get a zip of the source from [https://github.com/darchons/android-gdb the GitHub repo] (Get the zip because cloning takes a lot longer) |
| export PATH=~/android-toolchain/arm-linux-androideabi-4.4.3/bin:$PATH
| | # 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-android --with-python=yes --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/gdb |
|
| |
|
| Run configure and make for gdbserver (gdbserver comes with the android-gdb repository your checked out earlier):
| | ===== GDBServer ===== |
| 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
| |
|
| |
|
| The gdbserver binary will be located at ''android-gdbserver-objdir/gdbserver''.
| | Consider using the pre-built gdbserver binary 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 gdbserver |
|
| |
|
| Reminder: Don't use ~ in the paths you pass here, as Bash wouldn't evaluate it!
| | ==== Mac ==== |
|
| |
|
| ==== Mac OS X ==== | | ===== GDB ===== |
|
| |
|
| 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.
| | # Get a 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 build GDB. For example,<pre>port install bison flex ncurses texinfo python27</pre> |
| | # Run configure inside the source directory<pre>./configure --target=arm-elf-linux-android --with-python=yes --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/gdb |
|
| |
|
| Run configure and make for gdbserver (gdbserver comes with the android-gdb repository your checked out earlier):
| | ===== GDBServer ===== |
| 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
| |
|
| |
|
| The gdbserver binary will be located at ''android-gdbserver-objdir/gdbserver''.
| | Consider using the pre-built gdbserver binary 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/gdbserver |
|
| |
|
| === Create the moz-gdb directory === | | === Step 2. Creating JimDB directory === |
|
| |
|
| Once you've built JimDB, you need to create and populate a moz-gdb directory as explained below.
| | To get the most out of JimDB, in addition to the binaries, you need the Python scripts. But first, the scripts assume you have the following JimDB directory structure, |
| | |
| Indeed, GDB utilities assume the following moz-gdb directory structure:
| |
|
| |
|
| ./bin/ | | ./bin/ |
Line 137: |
Line 82: |
| python/ | | python/ |
|
| |
|
| Execute the following commands to create and set up the moz-gdb directory:
| | Therefore, you'd need to, |
| | | # Make a JimDB directory |
| mkdir -p moz-gdb/bin
| | # Copy gdb and gdbserver from steps above to bin/ |
| cp android-gdb-objdir/gdb/gdb moz-gdb/bin
| | # Clone the Python scripts to utils/ |
| cp android-gdbserver-objdir/gdbserver moz-gdb/bin
| | # Run bin/gdb |
| 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. | |
| <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 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).
| | For 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.com/darchons/android-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 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:
| | = Using JimDB = |
|
| |
|
| for file in $(adb shell ls /system/lib | tr "\n" " " | tr "\r" " "); do
| | == FAQ == |
| adb pull /system/lib/$file
| |
| done
| |
|
| |
|
| You may have to repeat this for other directories such as /vendor/lib for drivers.
| | === What is moz-gdb? |
| | * moz-gdb was a synonym for JimDB, but it's no longer used, to 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 "no":
| | === "error 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 you're using a --disable-optimize --enable-debug build of Fennec. Just --enable-debug doesn't seem to always be enough.
| | === JimDB is awesome now!! Can I buy you a $beverage? === |
| | * Yes |