Mobile/Fennec/Android: Difference between revisions

From MozillaWiki
< Mobile‎ | Fennec
Jump to navigation Jump to search
(Fix link to current build doc)
 
(676 intermediate revisions by 92 users not shown)
Line 1: Line 1:
== Setup a Build Environment ==
{{Admon/important|Fennec has been replaced by Fenix.  The build documentation has moved!|See the most up to date documentation at https://firefox-source-docs.mozilla.org/contributing/build/building_mobile_firefox.html}}
Below are instructions for setting up a build environment on Ubuntu. See [[Mobile/Fennec/Android_OtherBuildEnvs|the build docs here]] for instructions on setting up a build environment on other OSs.
=== 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 ===
Here is a table of contents of all the in-depth information you might need to find about Firefox for Android development.
==== 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 ==
New to the community? Welcome! [[Mobile/Get_Involved|Start here!]]
You build as you normally would (make -f client.mk), just with a differnt mozconfig


=== mozconfig ===
== Develop ==
Here's an example mozconfig that should get you building, modify it to meet your needs.
*[[Mobile/Get Involved|New contributor page]]
  # Add the correct paths here:
**[[Mobile/Fennec/Android/Suggested workflow|Suggested workflow]]
  ac_add_options --with-android-ndk="$HOME/android-ndk-r6"
*[https://developer.mozilla.org/en-US/docs/Simple_Firefox_for_Android_build Build documentation]
  ac_add_options --with-android-sdk="$HOME/android-sdk-linux_x86/platforms/android-8"
*[[Mobile/Fennec/Android/Testing|Testing]]
  ac_add_options --with-android-version=5
*[[Mobile/Fennec/Android/CommonTips|Common tips & how-to's]]
  ac_add_options --with-android-tools="$HOME/android-sdk-linux_x86/tools"
*[[Mobile/Fennec/Android/Multilocale_Builds|Multilocale Builds]] - how to build an apk containing multiple languages (instead of just en-US by default).
  ac_add_options --with-android-toolchain="$HOME/android-ndk-r6/toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86"
*[[Mobile/Fennec/Android/Development/Addons|Useful addons for development (e.g. copy profile)]]
  ac_add_options --with-android-platform="$HOME/android-ndk-r6/platforms/android-5/arch-arm"
*[[Mobile/Fennec/Android/AdvancedTopics|Advanced topics (e.g. special build configs & advanced debugging)]]
  # android options
*[https://gecko.readthedocs.org/en/latest/mobile/android/fennec/index.html In-tree Firefox for Android documentation]
  ac_add_options --enable-application=mobile
*[[Mobile/Triage|Triage]]
  ac_add_options --target=arm-linux-androideabi
*[[Mobile/Metrics|Metrics]]
  ac_add_options --with-endian=little
*[[Mobile/Fennec/Android/png_optimisation|png optimisation]] - a guide on how to prepare png and raster images for landing in the tree, in order to minimise their size. This includes details on webp conversion, when applicable.
  ac_add_options --with-ccache
 
  mk_add_options MOZ_OBJDIR=./objdir-droid
  mk_add_options MOZ_MAKE_FLAGS="-j9 -s"


== Testing ==
=== App and development overview ===
In general, android testing requires a parallel host build. Below the path to that build is assumed to be "../objdir-x86/dist/bin".
* [[Mobile/Fennec/Android/App_Structure|App Structure]]: Fennec is a combination of Java frontend code, Javascript glue and display code, and C++ rendering code. Here's a brief 9000m (30'000ft) overview of what each of those parts does.
=== Reftests ===
** [[Mobile/Fennec/Android/Build_Systems|Build Systems]]: Our app structure results in a complex build process. Moreover, we are in the process of migrating our builds from a custom (Makefile based) build, to using Gradle for the frontend/Java portions of our app. This is a brief description of our parallel build systems and what we're trying to achieve in the future.
  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==
=== Feature development ===
* [[Mobile/Distribution_Files|Distribution files]]
* [[Mobile/Fennec/Android/Java_telemetry|Java telemetry]]
* [[Mobile/Fennec/Android/Switchboard|Switchboard]]
* [[Mobile/Fennec/Android/Downloadable_Content|Downloadable Content]]


Nvidia's gdb is better: http://developer.download.nvidia.com/tegra/files/tegra-gdb-20100902.zip
=== Test results ===
*[https://scan.coverity.com/projects/firefox-mobile Coverity static analysis]


In order to attach before things get running, launch with:
=== Build infrastructure ===
  adb shell am start -a org.mozilla.gecko.DEBUG -n org.mozilla.fennec_unofficial/.App
*[[Mobile/Fennec/Android/Task Cluster notes|Task Cluster notes]]
*[[Mobile/Fennec/Android/mach_bootstrap_SDK_dependencies|`./mach bootstrap` SDK dependencies]]


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.
=== General developer resources ===
*[https://mozilla-version-control-tools.readthedocs.org/en/latest/hgmozilla/index.html Mercurial for Mozillians]
*[https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html Mozilla Phabricator User Guide]


this script [http://dump.lassey.us/debug.sh] will attach gdbserver for you
=== Crash Stats ===
 
* The crash-stats page lives at https://crash-stats.mozilla.com/home/product/FennecAndroid
===Env Vars===
** Be careful to select "'''FennecAndroid'''" under the product dropdown to see Firefox on Android crashes.
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:
*** Nightly has the name XX.0a1 (e.g. 52.0a1)
  adb shell am start -a android.activity.MAIN -n org.mozilla.fennec_unofficial/.App --es env0 VAR=val --es env1 FOO=bar
*** Aurora has the name XX.0a2 (e.g. 51.0a1 - the number is one lower than nightly)
 
*** Beta is XX.0bN (e.g. 50.0b12). N is increased every time a new beta is released (usually weekly).
You may need {{bug|578493}} if the env var you're using is tested before XRE_Main is called
**** '''Note:''' Multiple beta versions can be listed under the versions dropdown, the first one listed might not be the currently released beta.
 
*** Release is XX.0.N (e.g. 49.0.2). N is increased every time there is a dot release, we usually try to avoid dot releases.
===PR Logging===
** Beware: a single device (which potentially has a hardware issue and/or a user who has done something strange with their configuration) can result in a crash-spike on nightly, or even aurora - not every crash is something significant.
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
** You can view devices that are affected by selecting a crash-signature, then going to "Aggregations", followed by clicking on the "Aggregate on" dropdown and selecting "Android device". Some issues might be device or manufacturer specific.
  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
** To create a bugzilla entry for a given crash, open a crash report (if you are viewing a signature, go to "reports" and click on one of the items there). From the crash report search for "Bugzilla - Report this bug in" and select the appropriate module.
 
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 [[Mobile/Fennec/Android/GDBNoRoot|Fennec/Android/GDBNoRoot]] for another guide on how to do this.<br>
 
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:
 
&nbsp;!/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 [&nbsp;! -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&nbsp;: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

Latest revision as of 14:52, 16 February 2023

Important.png
Fennec has been replaced by Fenix. The build documentation has moved!
See the most up to date documentation at https://firefox-source-docs.mozilla.org/contributing/build/building_mobile_firefox.html

Here is a table of contents of all the in-depth information you might need to find about Firefox for Android development.

New to the community? Welcome! Start here!

Develop

App and development overview

  • App Structure: Fennec is a combination of Java frontend code, Javascript glue and display code, and C++ rendering code. Here's a brief 9000m (30'000ft) overview of what each of those parts does.
    • Build Systems: Our app structure results in a complex build process. Moreover, we are in the process of migrating our builds from a custom (Makefile based) build, to using Gradle for the frontend/Java portions of our app. This is a brief description of our parallel build systems and what we're trying to achieve in the future.

Feature development

Test results

Build infrastructure

General developer resources

Crash Stats

  • The crash-stats page lives at https://crash-stats.mozilla.com/home/product/FennecAndroid
    • Be careful to select "FennecAndroid" under the product dropdown to see Firefox on Android crashes.
      • Nightly has the name XX.0a1 (e.g. 52.0a1)
      • Aurora has the name XX.0a2 (e.g. 51.0a1 - the number is one lower than nightly)
      • Beta is XX.0bN (e.g. 50.0b12). N is increased every time a new beta is released (usually weekly).
        • Note: Multiple beta versions can be listed under the versions dropdown, the first one listed might not be the currently released beta.
      • Release is XX.0.N (e.g. 49.0.2). N is increased every time there is a dot release, we usually try to avoid dot releases.
    • Beware: a single device (which potentially has a hardware issue and/or a user who has done something strange with their configuration) can result in a crash-spike on nightly, or even aurora - not every crash is something significant.
    • You can view devices that are affected by selecting a crash-signature, then going to "Aggregations", followed by clicking on the "Aggregate on" dropdown and selecting "Android device". Some issues might be device or manufacturer specific.
    • To create a bugzilla entry for a given crash, open a crash report (if you are viewing a signature, go to "reports" and click on one of the items there). From the crash report search for "Bugzilla - Report this bug in" and select the appropriate module.
Retrieved from "https://wiki.allizom.org/index.php?title=Mobile/Fennec/Android&oldid=1245569"