Mobile/Fennec/Android/GDB: Difference between revisions

From MozillaWiki
< Mobile‎ | Fennec‎ | Android
Jump to navigation Jump to search
(Delete the instructions to 'gdb push gdbserver', since the section "Create the moz-gdb directory" is required, and the python scripts will take care of the copying of gdbserver from the moz-gdb dir)
No edit summary
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 \&#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


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&#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</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 \&#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


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&#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</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

Revision as of 19:04, 20 March 2013

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

Use #mobile on IRC for support.

Getting started

Using pre-built binaries

Instructions

  1. Download the latest pre-built binaries for your platform from this directory
  2. Extract to a user-writable directory
  3. Run 'git pull' from inside the utils/ directory to get the latest scripts
  4. Launch bin/gdb to start using JimDB!

Example

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

Custom-building

Step 1. Compiling the binaries

There are two things to build here: gdb and gdbserver

Linux

GDB
  1. Get a zip of the source from the GitHub repo (Get the zip because cloning takes a lot longer)
  2. Extract the zip
  3. You may need to install additional packages in order to build GDB. For example,
    sudo apt-get build-dep gdb
  4. Run configure inside the source directory
    ./configure --target=arm-elf-linux-android --with-python=yes --prefix=/nonexistent \
  --with-gdb-datadir=/nonexistent/utils --with-system-gdbinit=/nonexistent/utils/gdbinit
  5. Run make 
    make -j8
  6. 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,

  1. Use the source directory from above
  2. Make sure you have a copy of the Android NDK
  3. Run configure inside the gdb/gdbserver directory (following is for NDK r8d)
    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
  4. Run make 
    make -j8
  5. The compiled binary will be at gdbserver

Mac

GDB
  1. Get a zip of the source from the GitHub repo (Get the zip because cloning takes a lot longer)
  2. Extract the zip
  3. You may need to install additional packages in order to build GDB. For example,
    port install bison flex ncurses texinfo python27
  4. Run configure inside the source directory
    ./configure --target=arm-elf-linux-android --with-python=yes --prefix=/nonexistent \
  --with-gdb-datadir=/nonexistent/utils --with-system-gdbinit=/nonexistent/utils/gdbinit
  5. Run make 
    make -j8
  6. 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,

  1. Use the source directory from above
  2. Make sure you have a copy of the Android NDK
  3. Run configure inside the gdb/gdbserver directory (following is for NDK r8d)
    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
  4. Run make 
    make -j8
  5. 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,

  1. Make a JimDB directory
  2. Copy gdb and gdbserver from steps above to bin/
  3. Clone the Python scripts to utils/
  4. 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

FAQ

=== 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

"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

"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

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}'`

JimDB sucks! Halp!!

  • Come on #mobile on IRC
  • Or file a bug under Firefox for Android, JimDB component

JimDB is awesome now!! Can I buy you a $beverage?

  • Yes
Retrieved from "https://wiki.allizom.org/index.php?title=Mobile/Fennec/Android/GDB&oldid=639635"