Mobile/Fennec/Android/GDB: Difference between revisions

JimDB is no longer used. So add link to GV debugging document
No edit summary
(JimDB is no longer used. So add link to GV debugging document)
 
(66 intermediate revisions by 20 users not shown)
Line 1: Line 1:
Note: the names JimDB and moz-gdb seem to be used interchangeably, meaning the same thing.
= Deprecated =
This page is the information of deprecated debugging tools.  We recommend to use Android studio (https://mozilla.github.io/geckoview/tutorials/native-debugging.html).


= Using JimDB (Or, Android GDB with Niceness) =
= What JimDB? =
== Prebuilt binaries ==


=== Linux ===
JimDB is a fork of GDB used for simplifying Fennec development. It consists of two parts:


[https://github.com/darchons/android-gdb/downloads Download page]
* 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)


Run 'git pull' inside the utils directory to get the latest GDB utilities.
Use #mobile on IRC for support.


=== GDB utilities ===
= Getting started =


A set of tools to make Fennec development on Android easier.
== Using mach ==


[http://github.com/darchons/android-gdbutils Source and documentation].
You can use mach to fetch, install, configure, and run JimDB with one simple command. Note that if you are on OS X, mach may install JimDB correctly, but then try to debug using lldb. If that happens, you can still run JimDB manually from your ~/.mozbuild folder (you can find the full path in the output below).


== Building moz-gdb ==
  $ ./mach run --debug
  JimDB (arm) not found: /home/gbrown/.mozbuild/android-device/jimdb-arm does not exist
  Download and setup JimDB (arm)? (Y/n) y
  Installing JimDB (linux64/arm). This may take a while...
  From https://github.com/darchons/android-gdbutils
  * [new branch]      master    -> origin/master
  * [new tag]        gdbutils-2 -> gdbutils-2
  * [new tag]        initial-release -> initial-release
  1:45.57 /home/gbrown/.mozbuild/android-device/jimdb-arm/bin/gdb -q --args
  Fennec GDB utilities
    (see utils/gdbinit and utils/gdbinit.local on how to configure settings)
  1. Debug Fennec (default)
  2. Debug Fennec with env vars and args
  3. Debug using jdb
  4. Debug content Mochitest
  5. Debug compiled-code unit test
  6. Debug Fennec with pid
  Enter option from above: 1
  New ADB device is "emulator-5554"
  Using device emulator-5554
  Using object directory: /home/gbrown/objdirs/droid
  Set sysroot to "/home/gbrown/.mozbuild/android-device/jimdb-arm/lib/emulator-5554".
  Updated solib-search-path.
  Ignoring BHM signal.
  Using package org.mozilla.fennec_gbrown.
  Launching org.mozilla.fennec_gbrown... Done
  Attaching to pid 674... Done
  Setting up remote debugging... Done
  Ready. Use "continue" to resume execution.
  : No such file or directory.
  (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.
== Using pre-built binaries ==


=== Building gdb ===
=== Instructions ===
 
# Download the latest pre-built jimdb binaries for your host and device platforms from [https://people.mozilla.org/~nchen/jimdb this directory] (use 'jimdb-arm' for ARM devices and 'jimdb-x86' for x86 devices)
# Download the latest pre-built gdbserver binary for your device platform from [https://people.mozilla.org/~nchen/jimdb the same directory]
# Extract to a user-writable directory
# Replace the gdbserver binary in the jimdb-*/bin/ directory with the one you downloaded separately (it's newer)
# Run 'git pull' from inside the utils/ directory to get the latest scripts
# Launch bin/gdb to start using JimDB!
# OPTIONAL: For easier access, you can create a symlink to jimdb under, e.g., /usr/bin
 
=== Example ===
 
For ARM devices on Linux,
cd $HOME
wget https://people.mozilla.org/~nchen/jimdb/jimdb-arm-linux_x64.tar.bz2 # step 1
tar -xf jimdb-arm-linux_x64.tar.bz2 # step 3
cd jimdb-arm/utils && git pull # step 5
../bin/gdb # step 6
sudo ln -s $HOME/jimdb-arm/bin/gdb /usr/bin/jimdb # step 7
 
If you download the wrong x86 or x64 build, you might get an error like:
$ ./bin/gdb
./bin/gdb: error while loading shared libraries: libpython2.7.so.1.0: cannot open shared object file: No such file or directory
 
== Custom-building ==
 
=== Step 1. Compiling the binaries ===
 
There are two things to build here: gdb and gdbserver


==== Linux ====
==== Linux ====


Get required packages:
===== GDB =====
sudo apt-get install bison flex libncurses5-dev texinfo python2.7-dev
 
# Clone [https://github.com/darchons/android-gdb the GitHub repo] (do not use the Zip archive, as the build system will try to obtain a git changeset id)
# 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># ARM:&#10;./configure --target=arm-linux-android --with-python=yes --prefix=/nonexistent \&#10;  --with-gdb-datadir=/nonexistent/utils --with-system-gdbinit=/nonexistent/utils/gdbinit&#10;# x86:&#10;./configure --target=i686-pc-linux-android --with-python=yes --prefix=/nonexistent \&#10;  --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
If you see an error like:
<pre>
../../../../bfd/doc/bfd.texinfo:325: unknown command `colophon'
../../../../bfd/doc/bfd.texinfo:336: unknown command `cygnus'
Makefile:421: recipe for target 'bfd.info' failed
</pre>
you can fix this by running:
<pre>
sed -i -e 's/@colophon/@@colophon/' -e 's/doc@cygnus.com/doc@@cygnus.com/' bfd/doc/bfd.texinfo
</pre>
or by checking out a more recent branch (this bug is in the 7_5 branch).
 
===== 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&#10;# ARM:&#10;export PATH=$PATH:$NDK/toolchains/arm-linux-androideabi-4.6/prebuilt/linux-x86/bin&#10;./configure --host=arm-linux-androideabi --with-sysroot=$NDK/platforms/android-9/arch-arm&#10;# x86:&#10;export PATH=$PATH:$NDK/toolchains/x86-4.6/prebuilt/linux-x86/bin&#10;./configure --host=i686-linux-android --with-sysroot=$NDK/platforms/android-9/arch-x86</pre>
# Run make <pre>make -j8</pre>
# The compiled binary will be at gdbserver
 
==== Mac ====
 
===== GDB =====
 
# 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># ARM:&#10;./configure --target=arm-linux-android --with-python=yes --prefix=/nonexistent \&#10;  --with-gdb-datadir=/nonexistent/utils --with-system-gdbinit=/nonexistent/utils/gdbinit&#10;# x86:&#10;./configure --target=i686-pc-linux-android --with-python=yes --prefix=/nonexistent \&#10;  --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
 
===== 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&#10;# ARM:&#10;export PATH=$PATH:$NDK/toolchains/arm-linux-androideabi-4.6/prebuilt/darwin-x86/bin&#10;./configure --host=arm-linux-androideabi --with-sysroot=$NDK/platforms/android-9/arch-arm&#10;# x86:&#10;export PATH=$PATH:$NDK/toolchains/x86-4.6/prebuilt/darwin-x86/bin&#10;./configure --host=i686-linux-android --with-sysroot=$NDK/platforms/android-9/arch-x86</pre>
# Run make <pre>make -j8</pre>
# The compiled binary will be at gdb/gdbserver/gdbserver
 
=== Step 2. Creating JimDB directory ===
 
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,
 
./bin/
    gdb
    gdbserver
./utils/
    gdbinit
    python/
 
Therefore, you'd need to,
# Make a JimDB directory
# Copy gdb and gdbserver from steps above to bin/
# Clone the Python scripts to utils/
# Run bin/gdb
 
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
 
= Using JimDB =
 
== First run ==
 
In order to debug Fennec, JimDB needs a copy of your system libraries. When you try to debug Fennec on a particular device for the first time, JimDB will download the libraries from your device. This may take some time but will only need to run once. You may need to restart JimDB in order for debug symbols to work.
 
== Configuring JimDB ==
 
utils/gdbinit is the GDB command file that JimDB runs at launch. Open it in your favorite text editor to see configurable settings for JimDB.


Get source:
utils/gdbinit also loads utils/gdbinit.local. Because utils/gdbinit can change frequently across updates, it's recommended to copy your custom settings to utils/gdbinit.local, so that updates do not override your settings.
git clone git://github.com/darchons/android-gdb.git
cd android-gdb
git checkout android-gdb_7_3


Run configure and make:
For example, to configure the feninit.default.objdir option, paste the following line anywhere inside utils/gdbinit.local,
mkdir android-gdb-objdir
  python feninit.default.objdir = '/home/user/mozilla/central/objdir-android'
  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!
== FenInit ==


The gdb binary will be located at ''android-gdb-objdir/gdb/gdb''
FenInit is the Python script that simplifies launching Fennec on your device and setting up a debug environment. When JimDB starts, FenInit runs automatically and presents several options,


==== Mac OS X ====
# Debug Fennec (default)
# Debug Fennec with env vars and args
# Debug using jdb
# Debug content Mochitest
# Debug compiled-code unit test


NOTE (BenWa): It failed to built with clang on 2012/01/09
[[File:Jimdb-prompt.png]]
Get required packages:
port install bison flex ncurses texinfo python27


Get source:
=== Debug Fennec ===
git clone git://github.com/darchons/android-gdb.git
cd android-gdb
git checkout android-gdb_7_3


Run configure and make:
This is the default option. Once you choose an object directory to use, the script will automatically launch Fennec, and run GDBServer to attach to Fennec.
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 script tries to scan your user directory for object directories. For more control, see the [[#feninit.default.objdir|Configuration section]] on how to specify default object directories or where to scan for object directories.


The gdb binary will be located at ''android-gdb-objdir/gdb/gdb''
=== Debug Fennec with env vars and args ===


=== Building gdbserver ===
This option gives you the additional ability to specify environment variables and arguments when launching Fennec. See the [[#feninit.default.env|Configuration section]] on how to specify additional default environment variables and arguments.


==== Linux ====
=== Debug using jdb ===
 
This option will let you use the Java debugger (jdb) to debug the native Java portion of Fennec. This is the default option if you already have a previous JimDB debugging session running.
 
JDB support is experimental. It is able to at least set breakpoints, show source code, and examine objects.


Create an NDK toolchain:
=== Debug content Mochitest ===
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
This option will let you debug a regular Mochitest. Make sure Fennec is compiled with the '--enable-tests' option in the mozconfig file. Because running Mochitests require a copy of the XUL Runtime Environment (XRE), the script will offer to automatically download a copy of XRE for you, as well as launching the test harness. You can specify a file or a directory to test, or set TEST_PATH. Environment variables and arguments to the test harness are also supported.


Extract that toolchain somewhere:
=== Debug compiled-code unit test ===
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:
This option will let you debug a C++ test. Environment variables and arguments are supported.
export PATH=~/android-toolchain/arm-linux-androideabi-4.4.3/bin:$PATH


Run configure and make for gdbserver:
=== Configuration ===
  mkdir android-gdbserver-objdir
==== feninit.default.objdir ====
  cd android-gdbserver-objdir
* Set feninit.default.objdir to the default object directory. Note that once it is set, the script will not prompt you to choose an object directory.
  /path/to/android-gdb/gdb/gdbserver/configure --host=arm-linux-androideabi \
* Alternatively, if your object directories are called 'obj*' under your source directory, you can set feninit.default.objdir to the source directory itself. The script will scan the source directory and list all the object directories that it found.
  --with-sysroot=/PATH/TO/NDK/platforms/android-9/arch-arm
* Note that there have been problems in the past with using ~ and $HOME in the setting, so use absolute path for best results.
  make -j4
* PRO-TIP: Put the following code block inside gdbinit.local to always use the current directory as the object directory,
  python
  import os
  feninit.default.objdir = os.getcwd()
  end


The gdbserver binary will be located at ''android-gdbserver-objdir/gdbserver''.
==== feninit.default.srcroot ====
* Unlike the previous setting, feninit.default.srcroot specifies the directory containing all the source directories. This is convenient if you have 'src/mozilla-central', 'src/mozilla-inbound', 'src/mozilla-aurora', etc. In that case, you can set feninit.default.srcroot to 'src' and all the source directories will be scanned for object directories.
* Again, use absolute path for best results.
==== feninit.default.no_launch ====
* This settings is meant for B2G, and may not be useful for Fennec debugging.
==== feninit.default.gdbserver_port ====
* To debug Fennec on your device, GDB on your computer needs to talk to GDBServer on your device through a TCP port forwarded to your device through ADB.
* Normally, JimDB will use a random port. However, you can pick a specific port to use. This is useful in certain situations such as inside an SSH session. See [http://www.jnchen.com/blog/2012/11/tunnelling-adb this blog post].
==== feninit.default.jdwp_port ====
* Similar to feninit.default.gdbserver_port, except for using JDB for debugging.
==== feninit.default.env ====
* Specify the default environment variables to use when launching Fennec. Only used for the "Debug Fennec" options.
==== feninit.default.args ====
* Specify the default arguments to use when launching Fennec. Only used for the "Debug Fennec" options.
==== feninit.default.cpp_env ====
* Similar to [[#feninit.default.env|feninit.default.env]], except only used for the "Debug compiled-code unit test" option.
==== feninit.default.mochi_env ====
* Similar to [[#feninit.default.env|feninit.default.env]], except only used for the "Debug content Mochitest" option.
==== feninit.default.mochi_args ====
* Specify the default arguments to use when debugging Mochitest. Only used for the "Debug content Mochitest" option.
* Note that Mochitest arguments are arguments to the test harness (e.g. --remote-webserver), and not arguments to Fennec itself.
==== feninit.default.mochi_xre ====
* Specify the XRE directory to use, instead of letting the script download and manage an XRE copy.
==== feninit.default.mochi_harness ====
* Specify the directory containing the harness itself, i.e. "runtestsremote.py". Not needed normally.
==== feninit.default.mochi_xre_url ====
* Specify the directory on [https://ftp.mozilla.org ftp.mozilla.org] to use for downloading XRE. Not used if feninit.default.mochi_xre is specified.
==== feninit.default.mochi_xre_update ====
* Specify the XRE check for updates interval. Only used if the script is managing the XRE copy, and not used if feninit.default.mochi_xre_update is specified.


Reminder: Don't use ~ in the paths you pass here, as Bash wouldn't evaluate it!
== GDB commands specific to JimDB ==
=== set delay-add-remote-solibs ===
gdb> set delay-add-remote-solibs <0|1>
Default setting is 0. Set delay-add-remote-solibs to 1 to delay loading symbols when shared libraries are loaded. This may improve the set up time. However, you may need to use the "sharedlibrary" command to manually load symbols before using breakpoints.
=== monitor set ignore-ondemand ===
gdb> monitor set ignore-ondemand <0|1>
Default setting is 1. Set ignore-ondemand to 0 to not ignore segmentation faults generated by on-demand decompression. This setting may be needed to debug specific segmentation faults that are inadvertently being ignored. This command can only be run after attaching to the target, so it cannot be specified in gdbinit.local.


Install it on your device:
= FAQ =


adb push gdbserver /data/local
=== What is moz-gdb? ===
* moz-gdb was a synonym for JimDB, but it's no longer used, to avoid confusion


==== Mac OS X ====
=== "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


Setup a toolchain environment for your build:
=== "error while loading shared libraries: libtinfo.so.5" on Linux ===
  /PATH/TO/NDK/build/tools/make-standalone-toolchain.sh --install-dir=android-9-toolchain --platform=android-9
* 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


Run configure and make for gdbserver:
=== "Segmentation fault: 11" or "Illegal instruction: 4" on Mac OS X ===
mkdir android-gdbserver-objdir
* This may be due to incompatible OS X SDK versions. You should build your own JimDB binary to avoid the issue.
cd android-gdbserver-objdir
export PATH=android-9-toolchain/bin:$PATH
../android-gdb/gdb/gdbserver/configure --host=arm-linux-androideabi
make -j4


The gdbserver binary will be located at ''android-gdbserver-objdir/gdbserver''.
=== "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


Install it on your device:
=== "No module named printing" when debugging Fennec with JimDB ===
* The JimDB Python scripts lack several scripts included in regular GDB packages. To fix that, simply copy your local copy of these scripts to the JimDB utils/python directory. For example, on a typical Linux system, run
cp -r /usr/share/gdb/python/gdb $jimdb/utils/python/
* If you don't have these files, they are available [https://people.mozilla.org/~nchen/jimdb/gdb-python-lib.tar.bz2 here]; just extract it under $jimdb/utils/python/


adb push gdbserver /data/local
=== Random segmentation faults when debugging Fennec ===
* GDB can catch segmentation faults generated by on-demand decompression; just use "continue" to continue execution.
* Alternatively, specify the "MOZ_LINKER_ONDEMAND=0" environment variable when launching Fennec using Option 2. You can also put the option inside jimdb/utils/gdbinit.local.


=== Create the moz-gdb directory ===
=== 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}'`


Once you've built JimDB, you need to create and populate a moz-gdb directory as explained below.
=== "make: `[path]/mochitest-remote' is up to date." while trying to run Mochitests ===
* Delete the mochitest-remote file.


Indeed, GDB utilities assume the following moz-gdb directory structure:
=== "failed to run gdbserver" ===


./bin/
    "gdbserver" output:
     gdb
    /system/bin/sh: /data/local/tmp/gdbserver: not executable: magic 7F45
     gdbserver
    "run-as" output:
./utils/
     /data/local/tmp/gdbserver[1]: syntax error: '(' unexpected
    gdbinit
    "su -c" output:
    python/
     /system/bin/sh: su: not found
    [path]/jimdb-x86/bin/../utils/gdbinit:136: Error in sourced command file:
    failed to run gdbserver


Execute the following commands to create and set up the moz-gdb directory:
You are probably trying to run the x86 version on an ARM device. Download the ARM version of JimDB instead.


mkdir -p moz-gdb/bin
Alternatively, you may just have an out-of-date version of gdbserver. Check for an updated version in the link posted above.
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 ==
    "gdbserver" output:
    error: only position independent executables (PIE) are supported.


Now edit this file:
This means your build of gdbserver is too old for the Android version you're debugging on. You may need a newer platform sysroot and/or to add flags to gdb/gdbserver/Makefile to build a position-independent executable.


moz-gdb/utils/gdbinit
    CFLAGS += -fvisibility=default -fPIE
    LDFLAGS += -rdynamic -fPIE -pie


and uncomment (remove the #'s) and set the following variables:
=== JimDB sucks! Halp!! ===
  python feninit.default.objdir      # set it to your fennec object directory
* Come on #mobile on IRC
  python feninit.default.srcroot    # set it to your source directory
* Or file a bug under Firefox for Android, JimDB component


=== Linux ===
=== JimDB is awesome now!! Can I buy you a $beverage? ===
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.
Yes! See also {{bug|800000}}
<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 ==
=== Using `next` to traverse a function sometimes gets stuck with an error like "Unable to find end of function" ===
Try using the env-var MOZ_LINKER_ONDEMAND=0.


Once JimDB is properly set up, with a moz-gdb directory as described above, running Fennec in GDB is very easy:
=== Execution pauses often for "Program received signal SIG33, Real-time event 33." ===
This should be caught automatically, but try:
    handle SIG33 pass nostop noprint


  ./moz-gdb/bin/gdb
=== "Symbol not found: __PyErr_ReplaceException" ===
You should not use python 2.7.11.


This will automatically start gdbserver and fennec on the device, and start gdb on your computer.
See : https://github.com/conda/conda/issues/1367
Confirmed users
14

edits