Mobile/Fennec/Android: Difference between revisions

From MozillaWiki
< Mobile‎ | Fennec
Jump to navigation Jump to search
(update NDK download instructions)
(Fix link to current build doc)
 
(759 intermediate revisions by more than 100 users not shown)
Line 1: Line 1:
== Developing Fennec for Android ==
{{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}}


This page contains developer information about [[Mobile/Platforms/Android|Firefox for Android]], part of the [[Fennec]] project.
Here is a table of contents of all the in-depth information you might need to find about Firefox for Android development.


To download Firefox for Android or learn more about it, see the main '''[[Mobile/Platforms/Android|Fennec for Android]]''' page.
New to the community? Welcome! [[Mobile/Get_Involved|Start here!]]


== Current Status ==
== Develop ==
*[[Mobile/Get Involved|New contributor page]]
**[[Mobile/Fennec/Android/Suggested workflow|Suggested workflow]]
*[https://developer.mozilla.org/en-US/docs/Simple_Firefox_for_Android_build Build documentation]
*[[Mobile/Fennec/Android/Testing|Testing]]
*[[Mobile/Fennec/Android/CommonTips|Common tips & how-to's]]
*[[Mobile/Fennec/Android/Multilocale_Builds|Multilocale Builds]] - how to build an apk containing multiple languages (instead of just en-US by default).
*[[Mobile/Fennec/Android/Development/Addons|Useful addons for development (e.g. copy profile)]]
*[[Mobile/Fennec/Android/AdvancedTopics|Advanced topics (e.g. special build configs & advanced debugging)]]
*[https://gecko.readthedocs.org/en/latest/mobile/android/fennec/index.html In-tree Firefox for Android documentation]
*[[Mobile/Triage|Triage]]
*[[Mobile/Metrics|Metrics]]
*[[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.


* [[Android/Status|Current bugs]]
=== App and development overview ===
* Most things mostly working
* [[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.
* Keyboard input works but needs more work
** [[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.
* Audio randomly works


== Download Source Code ==
=== 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]]


Check out the mozilla-central [[Mercurial]] repository, and the separate mobile-browser repository in a subdirectory called "mobile":
=== Test results ===
*[https://scan.coverity.com/projects/firefox-mobile Coverity static analysis]


hg clone http://hg.mozilla.org/mozilla-central
=== Build infrastructure ===
cd mozilla-central
*[[Mobile/Fennec/Android/Task Cluster notes|Task Cluster notes]]
hg clone http://hg.mozilla.org/mobile-browser mobile
*[[Mobile/Fennec/Android/mach_bootstrap_SDK_dependencies|`./mach bootstrap` SDK dependencies]]


== Install Dependencies ==
=== 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]


* Standard [https://developer.mozilla.org/En/Linux_Build_Prerequisites Linux build environment] or [https://developer.mozilla.org/En/Developer_Guide/Build_Instructions/Mac_OS_X_Prerequisites Mac OS X build environment]
=== Crash Stats ===
* [http://ftp.mozilla.org/pub/mozilla.org/mobile/source/ Android NDK] - This version is based on the original [http://developer.android.com/sdk/ndk/ Android NDK], modified to include C++ standard libraries and sys/queue.h.
* The crash-stats page lives at https://crash-stats.mozilla.com/home/product/FennecAndroid
* [http://developer.android.com/sdk/ Android SDK]
** 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)
=== Set up a build environment ===
*** 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).
==== Ubuntu 10.04 ====
**** '''Note:''' Multiple beta versions can be listed under the versions dropdown, the first one listed might not be the currently released beta.
  sudo add-apt-repository "deb http://archive.canonical.com/ lucid partner"
*** 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.
  sudo apt-get update
** 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.
  sudo apt-get build-dep firefox
** 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.
  sudo apt-get install sun-java6-jre sun-java6-plugin sun-java6-fonts sun-java6-jdk ia32-libs
** 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.
  wget http://dl.google.com/android/android-sdk_r06-linux_86.tgz
  tar xjf android-sdk_r06-linux_86.tgz
  wget http://ftp.mozilla.org/pub/mozilla.org/mobile/source/android-ndk-r4c-0moz3.tar.bz2
  tar xjf http://ftp.mozilla.org/pub/mozilla.org/mobile/source/android-ndk-r4c-0moz3.tar.bz2
  .android-sdk-linux_86/tools/android update sdk
 
=== Quickstart (Linux) ===
 
Download the SDK and NDK:
 
wget http://dl.google.com/android/android-sdk_r06-linux_86.tgz
wget http://ftp.mozilla.org/pub/mozilla.org/mobile/source/android-ndk-r4c-0moz3.tar.bz2
 
Then unpack them:
 
tar xvfj android-ndk-r4c-0moz3.tar.bz2
tar xvfz android-sdk_r06-linux_86.tgz
 
Install Java runtime and JDK:
 
sudo apt-get install sun-java6-jre sun-java6-plugin sun-java6-fonts sun-java6-jdk
 
'''Ubuntu note:''' be sure to install the Sun or OpenJDK version of Java, gcj will not work. In Ubuntu 10.04 Sun Java was moved to the Partner repository. Open the Software Center, edit Software Sources and enable the Partner repository.
 
Android SDK needs to be setup manually.
 
* In the SDK directory, run tools/android
* Check Settings->Force https://... sources to be fetched using http://...
* Click Save & Apply
* Installed Packages->Update All...
* Select at least the Android SDK, API level 6.  Optionally you can install API levels 4 and 8.
* Click Install, Accept, etc.
 
== Build Fennec for Android ==
 
=== Full Build ===
 
Normal Firefox build, with the following mozconfig. (Put this in a file called "mozconfig" in your top-level source directory.)
 
# Uncomment these two lines to use objdir with client.mk
#OBJDIR=objdir-android
#mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/$OBJDIR
# Add the correct paths here:
ac_add_options --with-android-ndk="CHANGE/PATH/TO/android-ndk-r4"
ac_add_options --with-android-sdk="CHANGE/PATH/TO/android-sdk-linux_86/platforms/android-8"
ac_add_options --with-android-tools="CHANGE/PATH/TO/android-sdk-linux_86/tools"
# android options
ac_add_options --enable-application=mobile
ac_add_options --target=arm-android-eabi
ac_add_options --with-endian=little
ac_add_options --disable-tests
export MOZ_DEBUG_SYMBOLS=1
 
A standard build should succeed with those paths.
 
After that build finishes, a <tt>make -C embedding/android</tt> (in the OBJDIR if one exists) should generate a fennec.apk that's installable on an Android device using <tt>adb install fennec.apk</tt>
 
=== JS/NSPR only ===
 
In the commands below, replace these with the appropriate paths:
 
* <tt>$NDK</tt> is the NDK location
* <tt>$moz</tt> is the mozilla-droid repo checkout
* <tt>$out</tt> is some base destination directory
 
First, regenerate configure in the js dir (the nspr configure is checked in):
cd $moz/js/src && autoconf2.13
 
Then create a nspr directory, configure nspr, and build it:
 
cd $out
mkdir nspr
cd nspr
$moz/nsprpub/configure \
  --target=arm-android-eabi \
  --with-android-ndk=$NDK
make -s
 
Then do the same for JS, telling it where to find the NSPR you just built:
 
cd $out
mkdir js
cd js
$moz/js/src/configure \
  --target=arm-android-eabi \
  --with-android-ndk=$NDK \
  --with-nspr-cflags=-I$out/nspr/dist/include/nspr \
  --with-nspr-libs='-L$out/nspr/dist/lib -lnspr4 -lplc4 -lplds4' \
  --enable-threadsafe \
  --with-endian=little \
  --with-arm-kuser
make -s
 
More information about NSPR is on [[Android/NSPR|this separate page]].
 
== Run Fennec on Android ==
 
You'll need to copy the NSPR libraries and the js shell to the emulator or your device.  Whether you're running on a physical device or an emulator, /data/local should be writable by the user.
 
cd $out/nspr/dist/lib
for f in *.so ; do adb push $f /data/local ; done
cd $out/js/shell
adb push js /data/local
 
Then, connect to a shell on the device, and run js (adb shell prompts prefixed with "android"):
 
% adb shell
android% cd /data/local
android% LD_LIBRARY_PATH=. ./js
js> 1+1
2
 
== Debugging with GDB ==
 
=== Preparation ===
 
Debugging with gdbserver requires root access.  If you have not rooted your phone, search the web for instructions for your particular device.
 
If you do not already have gdbserver on your device (use <tt>adb shell gdbserver</tt> to check), you can push a pre-built version from the NDK.
 
adb push /PATH/TO/android-ndk-r4/build/prebuilt/linux-x86/arm-eabi-4.4.0/bin/gdbserver /data/local
 
Note: Fennec might crash when attaching using the gdb binaries included in the Google NDK. In that case use the nVidia gdb binaries [http://tegradeveloper.nvidia.com/tegra/downloads here]
 
The images included with the SDK for emulation are [http://www.yaffs.net/ yaffs2] images and require some work to mount and extract files from. An alternative is to just copy the necessary files from your device via adb pull. /system/bin/linker is referred to by absolute path so setting solib-absolute-prefix in gdb will be necessary for it to be found. Other files can be placed anywhere as long as they can be found in solib-search-path.
 
In short, find a directory to put some libraries, make sure adb is in your path, and paste this into your terminal:
 
adb pull /system/bin/linker . &&
adb pull /system/bin/app_process . &&
mkdir -p system/bin &&
mv linker system/bin &&
for LIB in libc.so libm.so libstdc++.so liblog.so libz.so libGLESv1_CM.so
do
adb pull /system/lib/$LIB .
done
 
Alternately, unpack the system image of your device somewhere. (eg. signed-dream_devphone_userdebug-ota-14721.zip)
 
=== Attach GDB ===
 
* launch in debug mode:
  adb shell am start -a org.mozilla.gecko.DEBUG -n org.mozilla.fennec/org.mozilla.fennec.App
* Forward a port for gdb between your device and computer using adb. Any port you can open should work. 1234 is used here.
** (Host) adb forward tcp:1234 tcp:1234
* Find the pid of your process if you don't know it. Every message in adb logcat specifies the PID of the process that produced the message, so gecko's PID can be found there, or you can look at the second column of <tt>adb shell ps|grep fennec</tt>.
* Attach gdbserver to the process
** (Device) <tt>gdbserver localhost:1234 --attach 6036</tt>
** Use <tt>/data/local/gdbserver</tt> if gdbserver is not in your PATH.
Attached; pid = 6036
Listening on port 1234
* Run arm-eabi-gdb on your binary. (android-ndk-1.6_r1/build/prebuilt/linux-x86/arm-eabi-4.2.1/bin) For debugging gecko, a copy of app_process from your device should be used.
** (Host) ~/android-ndk-1.6_r1/build/prebuilt/linux-x86/arm-eabi-4.2.1/bin/arm-eabi-gdb app_process
GNU gdb 6.6
Copyright (C) 2006 Free Software Foundation, Inc.
GDB is free software, covered by the GNU General Public License, and you are
welcome to change it and/or distribute copies of it under certain conditions.
Type "show copying" to see the conditions.
There is absolutely no warranty for GDB.  Type "show warranty" for details.
This GDB was configured as "--host=x86_64-unknown-linux-gnu --target=arm-elf-linux"...
* Configure solib-absolute-prefix. This will point to the directory where you unpacked your system image or where you copied the libraries.
** (Host gdb) set solib-absolute-prefix /home/user/android/sysimg
* Configure solib-search-path. This needs to point to the directories you need debugging symbols from - /system/lib or where ever you copied the libraries.
** (Host gdb) set solib-search-path /home/user/android/sysimg/system/lib:/home/user/android/moz-build/dist/bin
* Connect to gdbserver
** (Host gdb) target remote localhost:1234
* These three Host gdb commands can be placed in a .gdbinit file to automate future gdb runs. .gdbinit should be located where you normally run gdb.
 
You can use the script below to setup gdbserver with a single command:
 
#!/bin/sh
PORT=1234
adb forward tcp:$PORT tcp:$PORT &&
adb shell am start -a org.mozilla.gecko.DEBUG -n org.mozilla.fennec/org.mozilla.fennec.App &&
PID=`adb shell ps|grep org.mozilla.fennec|cut -c11-16` && sleep 3 &&
adb shell /data/local/gdbserver localhost:$PORT --attach $PID
 
== Profiling ==
 
oprofile is enabled in the kernel on the G1 dev phone and SDK emulator images. The oprofile programs (opcontrol, oprofiled) are in <tt>/system/xbin</tt>.
 
== Android Development Tips ==
 
* You can build a full Android OS from source [http://wiki.cyanogenmod.com/index.php/Building_from_source following the instructions on Cyanogen's site]. This helps tremendously with debugging.
* You might want to change the emulator options to give it enough space to install and run Fennec: <tt>emulator -partition-size 256 -memory 512</tt>
* Pass command line arguments to Fennec as "extras" using the -es argument: <tt>adb shell am start -n org.mozilla.fennec/org.mozilla.fennec.App -es -safe-mode</tt>
 
Nightly builds are available unsigned, so that you can sign them with your local debug key and install them on top of your own debug builds (without uninstalling and losing your profile). To sign and install the unsigned nightly build:
 
wget http://ftp.mozilla.org/pub/mozilla.org/mobile/nightly/latest-mozilla-central-android-r7/gecko-unsigned-unaligned.apk
jarsigner -keystore ~/.android/debug.keystore -storepass android -keypass android gecko-unsigned-unaligned.apk androiddebugkey
zipalign -f -v 4 gecko-unsigned-unaligned.apk gecko-signed-aligned.apk
adb install -r gecko-signed-aligned.apk
 
== Other Resources ==
 
* [https://wiki.mozilla.org/User:Joel_Reymont/Android_Notes Joel's Notes]
* [https://wiki.mozilla.org/User:VladVukicevic/Android_Notes Vlad's Notes]
* [http://hg.mozilla.org/users/vladimir_mozilla.com/android-testapp/ Vlad's Test App Hg Repo]

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://dev.wikimo.nonprod.webservices.mozgcp.net/index.php?title=Mobile/Fennec/Android&oldid=1245569"