Mobile/Fennec/Android

Setup a Build Environment

Quick Script

 sudo add-apt-repository ppa:ferramroberto/java 
 sudo apt-get update
 sudo apt-get install sun-java6-jdk mercurial ccache
 sudo apt-get build-dep firefox
 wget http://dl.google.com/android/ndk/android-ndk-r6-linux-x86.tar.bz2
 tar -xjf android-ndk-r6-linux-x86.tar.bz2
 wget http://dl.google.com/android/android-sdk_r12-linux_x86.tgz
 tar -xzf android-sdk_r12-linux_x86.tgz
 # go get lunch, this will take a while
 ./android-sdk-linux_x86/tools/android update sdk -u
 ./android-sdk-linux_x86/tools/android update adb

Explained

Install Java

First install the Sun Java jdk6, which the Android SDK depends on If you're on Ubuntu 11.04, you'll need to use an addtional repo (ppa) as its not available in the partners repo yet. Others report success using the Maverick partners repo to get it.

 sudo add-apt-repository ppa:ferramroberto/java 
 sudo apt-get update
 sudo apt-get install sun-java6-jdk

Install Gecko Requirements

Then install the usual stuff needed for a firefox build, you probably already have it

 sudo apt-get install mercurial ccache
 sudo apt-get build-dep firefox

Install Android NDK

Download and extract the NDK. NDK revs 4, 5 and 6 have been tested and confirmed to work.

 wget http://dl.google.com/android/ndk/android-ndk-r6-linux-x86.tar.bz2
 tar -xjf android-ndk-r6-linux-x86.tar.bz2

Install Android SDK

You should just install the latest sdk, we set the API level in our manifest files. The sdk download will take a while, make sure you have a decent internet connection and go get coffee, or maybe lunch.

 wget http://dl.google.com/android/android-sdk_r12-linux_x86.tgz
 tar -xzf android-sdk_r12-linux_x86.tgz
 ./android-sdk-linux_x86/tools/android update sdk -u
 ./android-sdk-linux_x86/tools/android update adb

Build

You build as you normally would (make -f client.mk), just with a differnt mozconfig

mozconfig

Here's an example mozconfig that should get you building, modify it to meet your needs.

 # Add the correct paths here:
 ac_add_options --with-android-ndk="$HOME/android-ndk-r6"
 ac_add_options --with-android-sdk="$HOME/android-sdk-linux_x86/platforms/android-8"
 ac_add_options --with-android-version=5
 ac_add_options --with-android-tools="$HOME/android-sdk-linux_x86/tools"
 ac_add_options --with-android-toolchain="$HOME/android-ndk-r6/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86"
 ac_add_options --with-android-platform="$HOME/android-ndk-r6/platforms/android-5/arch-arm"
 # android options
 ac_add_options --enable-application=mobile
 ac_add_options --target=arm-linux-androideabi
 ac_add_options --with-endian=little
 ac_add_options --with-ccache
 
 mk_add_options MOZ_OBJDIR=./objdir-droid
 mk_add_options MOZ_MAKE_FLAGS="-j9 -s"

Testing

In general, android testing requires a parallel host build. Below the path to that build is assumed to be "../objdir-x86/dist/bin".

Reftests

 MOZ_HOST_BIN="../objdir-x86/dist/bin/" make reftest-remote

Mochitests

 MOZ_HOST_BIN="../objdir-x86/dist/bin/" make mochitest-remote 

xpcshell

progress being tracked in bug 661282 and bug 668349

Debugging

Nvidia's gdb is better: http://developer.download.nvidia.com/tegra/files/tegra-gdb-20100902.zip

In order to attach before things get running, launch with:

  adb shell am start -a org.mozilla.gecko.DEBUG -n org.mozilla.fennec_unofficial/.App

and just click launch once gdb is attached. If you need to debug a crash that happens before XRE_Main is called, the patch on bug 572247 may be useful.

this script [1] will attach gdbserver for you

Env Vars

If you need to set an env var at run time, use append --es env# VAR=VAL to your activity manager command where # is the ordered number of variables for example:

 adb shell am start -a android.activity.MAIN -n org.mozilla.fennec_unofficial/.App --es env0 VAR=val --es env1 FOO=bar

You may need bug 578493 if the env var you're using is tested before XRE_Main is called

PR Logging

You can use the env vars as described above to make logging work (along with bug 578493). With just that you can log to a file

 adb shell am start -a android.activity.MAIN -n org.mozilla.fennec/org.mozilla.fennec.App --es env0 NSPR_LOG_MODULES=all:5 --es env1 NSPR_LOG_FILE=/mnt/sdcard/log.txt

With the patch on bug 578496 you can have the logging directed to the android logs and as such only need:

 adb shell am start -a android.activity.MAIN -n org.mozilla.fennec/org.mozilla.fennec.App --es env0 NSPR_LOG_MODULES=all:5

debugging without rooting

with Froyo you can debug without rooting your phone. Instructions are below. See also Fennec/Android/GDBNoRoot for another guide on how to do this.

First thing, to make this work with the nvidia gdb (which I found more reliable than the android r3 gdb) you need to modify install.sh and debug.sh.

first, change the location where install.sh copies gdbserver to somewhere writable by a non-root process. I used /data/local. Be sure to update that both in the push command and the chmod command.

second, update debug.sh with the new location of gdbserver.

finally, you'll need to add run-as $2 to the adb shell command that launches gdbserver. In the end you should have: install.sh:

 #!/bin/sh
mkdir lib
adb push prebuilt/gdbserver /data/local
adb shell chmod 755 /data/local/gdbserver
for file in $(adb shell ls /system/lib | tr "\n" " " | tr "\r" " "); do
   adb pull /system/lib/$file lib
done
adb pull /system/bin/app_process lib 

debug.sh:

 !/bin/sh
if [ $# -ne 2 ]
then
   echo "usage: $0 /path/to/your/library.so packagename.of.your.activity"
   echo "for example:"
   echo "  $0 /code/mydemo/libs/armeabi/libmydemo.so com.nvidia.devtech.mydemo"
   exit
fi

if [ ! -f $1 ]
then
   echo "ERROR: That library file doesn't exist"
   exit
fi

cp $1 lib

p=`adb shell ps | grep $2 | awk '{print $2}'`
if [ "$p" = "" ];
then
   echo "ERROR: That doesn't seem to be a running process. Please make sure your"
   echo "application has been started and that you are using the correct"
   echo "namespace argument."
   exit
fi

adb forward tcp:12345 tcp:12345
adb shell run-as $2 /data/local/gdbserver --attach :12345 $p

Other useful tips and tricks

killer script

 #!/bin/sh
 if [ $# -ne 1 ]
 then
     echo "usage: $0  packagename.of.your.activity"
     echo "for example:"
     echo "  $0 org.mozilla.fennec"
     exit
 fi
 
 p=`adb shell ps | grep $1 | awk '{print $2}'`
 if [ "$p" = "" ];
 then
     echo "ERROR: That doesn't seem to be a running process. Please make sure your"
     echo "application has been started and that you are using the correct"
     echo "namespace argument."
     exit
 fi
 
 adb shell run-as $1 kill $p

.gdbinit

this is an example .gdbinit that uses the symbols from a locally built rom and automatically attaches to gdbserver

 set solib-search-path /home/blassey/android/system/out/target/product/passion/symbols/system/bin:/home/blassey/android/system/out/target/product/passion/symbols/system/lib/:/home/blassey/src/ndk5-m-c/objdir-droid-dbg/dist/bin
 set solib-absolute-prefix /home/blassey/android/system/out/target/product/passion/symbols/system/lib/
 target remote localhost:12345