Mobile/Fennec/Android: Difference between revisions

From MozillaWiki
< Mobile‎ | Fennec
Jump to navigation Jump to search
(Fix link to current build doc)
 
(540 intermediate revisions by 83 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.  
Here is a table of contents of all the in-depth information you might need to find about Firefox for Android development.


=== Quick Script  ===
New to the community? Welcome! [[Mobile/Get_Involved|Start here!]]


# ensure that the "partner" repositories are enabled in /etc/apt/sources.list, or sun-java6-jdk won't be found
== Develop ==
# Ubuntu 11.10 Java has been removed from partner, can be downloaded from Oracle
*[[Mobile/Get Involved|New contributor page]]
sudo apt-get update
**[[Mobile/Fennec/Android/Suggested workflow|Suggested workflow]]
sudo apt-get install sun-java6-jdk mercurial ccache
*[https://developer.mozilla.org/en-US/docs/Simple_Firefox_for_Android_build Build documentation]
sudo apt-get build-dep firefox
*[[Mobile/Fennec/Android/Testing|Testing]]
wget http://dl.google.com/android/ndk/android-ndk-r5c-linux-x86.tar.bz2
*[[Mobile/Fennec/Android/CommonTips|Common tips & how-to's]]
tar -xjf android-ndk-r5c-linux-x86.tar.bz2
*[[Mobile/Fennec/Android/Multilocale_Builds|Multilocale Builds]] - how to build an apk containing multiple languages (instead of just en-US by default).
wget http://dl.google.com/android/android-sdk_r15-linux.tgz
*[[Mobile/Fennec/Android/Development/Addons|Useful addons for development (e.g. copy profile)]]
tar -xzf android-sdk_r15-linux.tgz
*[[Mobile/Fennec/Android/AdvancedTopics|Advanced topics (e.g. special build configs & advanced debugging)]]
# go get lunch, this will take a while
*[https://gecko.readthedocs.org/en/latest/mobile/android/fennec/index.html In-tree Firefox for Android documentation]
./android-sdk-linux/tools/android update sdk -u
*[[Mobile/Triage|Triage]]
./android-sdk-linux/tools/android update adb
*[[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.


=== App and development overview ===
* [[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.
** [[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.


If you're using a 64-bit Ubuntu install, you'll need ia32-libs to allow the toolchain binaries to run.
=== 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]]


  sudo apt-get install ia32-libs
=== Test results ===
*[https://scan.coverity.com/projects/firefox-mobile Coverity static analysis]


If you're using 64-bit Fedora install
=== Build infrastructure ===
*[[Mobile/Fennec/Android/Task Cluster notes|Task Cluster notes]]
*[[Mobile/Fennec/Android/mach_bootstrap_SDK_dependencies|`./mach bootstrap` SDK dependencies]]


  yum install glibc.i686 ncurses-libs.i686 libstdc++.i686 zlib.i686
=== 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]


=== Explained  ===
=== Crash Stats ===
 
* The crash-stats page lives at https://crash-stats.mozilla.com/home/product/FennecAndroid
==== Install Java  ====
** 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)
First install the Sun Java jdk6, which the Android SDK depends on. If you're on Ubuntu (pre-11.10), you'll need to [https://help.ubuntu.com/community/Repositories/Ubuntu#Adding_Canonical_Partner_Repositories enable the partners repo] to get it.
*** 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).
sudo apt-get update
**** '''Note:''' Multiple beta versions can be listed under the versions dropdown, the first one listed might not be the currently released beta.
sudo apt-get install sun-java6-jdk
*** 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 update-java-alternatives -s java-6-sun
** 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.
# Ubuntu 11.10
** 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.
Download Java from Oracle
sudo mkdir /opt/java
sudo mv ~/Downloads/jdk-6u29-linux-x64.bin
sudo chmod +x ./jdk-6u29-linux-x64.bin
sudo ./jdk-6u29-linux-x64.bin
ln -f -s /opt/java/jdk1.6.0_29/bin/* /usr/local/bin/
# something like sudo update-alternatives --install /usr/local/bin/java java /opt/java/jdk1.6.0_29/bin/ 1 is close to the distro way of registering java
 
==== 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 [http://developer.android.com/sdk/ndk/ Android NDK]. NDK revs 4, and 5 have been tested and confirmed to work. NDK rev 7 is known to NOT work (see bug 712679). NDK rev 6b and later also have issues (http://code.google.com/p/android/issues/detail?id=23203).
 
wget http://dl.google.com/android/ndk/android-ndk-r5c-linux-x86.tar.bz2
tar -xjf android-ndk-r5c-linux-x86.tar.bz2
 
or the same thing with http://dl.google.com/android/ndk/android-ndk-r5c-darwin-x86.tar.bz2 on Mac.
 
==== Install Android SDK  ====
 
You should just install the latest [http://developer.android.com/sdk/ Android 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_r13-linux_x86.tgz
tar -xzf android-sdk_r13-linux_x86.tgz
./android-sdk-linux_x86/tools/android update sdk -f -u
./android-sdk-linux_x86/tools/android update adb
 
The Mac SDK is at http://dl.google.com/android/android-sdk_r16-macosx.zip
 
You will probably want to add the SDK's "tools" and "platform-tools" directory to the PATH environment variable in your shell, so that you can run [http://developer.android.com/guide/developing/tools/adb.html adb] and other tools easily. For example, if you installed the SDK in $HOME/opt, you could add the following line to the end of your .bashrc:
 
  export PATH=$PATH:$HOME/opt/android-sdk-linux_x86/platform-tools:$HOME/opt/android-sdk-linux_x86/tools
 
== Build  ==
 
You build as you normally would (make -f client.mk), just with a different mozconfig.
 
Instructions for getting Mozilla source code are here: https://developer.mozilla.org/en/Mozilla_Source_Code_(Mercurial)
 
Here's an example mozconfig:
 
# Add the correct paths here:
ac_add_options --with-android-ndk="$HOME/android-ndk-r5c"
ac_add_options --with-android-sdk="$HOME/android-sdk-linux_x86/platforms/android-13"
ac_add_options --with-android-version=5
# android options
ac_add_options --enable-application=mobile/android
ac_add_options --target=arm-linux-androideabi
ac_add_options --with-ccache
ac_add_options --enable-tests
mk_add_options MOZ_OBJDIR=./objdir-droid
mk_add_options MOZ_MAKE_FLAGS="-j9 -s"
 
 
  hg clone http://hg.mozilla.org/mozilla-central/ src
  cd src
  vi mozconfig-droid
  export MOZCONFIG=~/src/mozconfig-droid
  make -f client.mk
 
=== Increase linking speed (AKA using gold) ===
 
On some systems, linking libxul can takes several minutes. Using ''gold'' instead of ''ld'' can reduce this time (from around 7 minutes to a bit more than 1 minute on my machine ; YMMV, on another machine, it gets from 25 seconds to 10, or from 2 minutes to 1 minute with all system caches dropped).
 
To use gold, you have to recompile toolchain in the ndk with a newer binutils.
 
Go to your Android NDK directory then update the toolchain sources:
  ./build/tools/download-toolchain-sources.sh src
 
(If the above fails because it can't clone from android.git.kernel.org, try "./build/tools/download-toolchain-sources.sh --git-base=https://android.googlesource.com/toolchain src" to download from android.googlesource.com instead).
 
Now, you have to download the latest binutils (currently 2.21.53), go there:
  ftp://sourceware.org/pub/binutils/snapshots/
 
Extract it in src/binutils (in the NDK directory). That should create a new directory named ''binutils-<VERSION>''.
 
Before building the toolchain, we have to make sure gold is used as the default linker, open ''build/tools/build-gcc.sh'' and add:
  --enable-gold=default \
in the configure script options. This should be after this line ''# configure the toolchain'', near the line 200.
 
You are all set and ready to rebuild the toolchain, run this:
  ./build/tools/build-gcc.sh --binutils-version=<BINUTILS_VERSION> $(pwd)/src $(pwd) arm-linux-androideabi-4.4.3
 
Finally, you can call this command and make sure the first line output is ''GNU gold (GNU Binutils [...])'':
  toolchains/arm-linux-androideabi-4.4.3/prebuilt/linux-x86/arm-linux-androideabi/bin/ld --version
 
=== Partial Builds: Beware the startup cache! ===
 
Partial builds for updated Javascript files may not work correctly if installed with adb install -r. This section describes the issue.
 
Developers who frequently update .js files sometimes like to only re-build the module they have updated. For instance:
 
  make -C mobile/android && make package
 
This should result in the APK being properly updated with the updated Javascript, BUT the change may not be reflected on the device because of complications arising from the startup cache. If the startup cache from a previous run of Fennec exists on the device and contains an old version of the recently updated Javascript, Fennec will likely use the old version.
 
The startup cache is located in the profile, so deleting the profile ensures a new startup cache:
 
  adb uninstall org.mozilla.fennec
  adb install dist/fennec*.apk
 
Note that:
 
  adb install -r dist/fennec*.apk
 
retains the profile (and startup cache) -- so that's still a problem.
 
None of this is a problem with full builds:
 
  make -f client.mk && make package
  adb install -r dist/fennec*.apk
 
works just fine, because the startup cache respects the buildid: If the buildid found in an APK is different from the buildid used when the startup cache was last updated, the startup cache is automatically deleted. A full build correctly updates the buildid -- a partial build may not.
 
A possible way (***I have not conclusively tested this***) to do a partial build, retain an old profile, and ensure the buildid is updated and the startup cache is subsequently deleted is:
 
  make export && make -C mobile/android && make -C toolkit/xre && make package
  adb install -r dist/fennec*.apk
 
Note that make export is necessary to update the buildid and make -C toolkit/xre is required to generate application.ini.h, trigger a rebuild of nsAndroidStartup.cpp, and update libxul.so.
 
== Install and run ==
 
Run `make package` in your objdir to generate an APK file.  The package will have a name like "objdir-droid/dist/fennec-9.0a1.en-US.android-arm.apk":
 
make -C <objdir-droid> package
 
[http://developer.android.com/guide/developing/device.html Connect your Android device and set up USB debugging], then install the fennec package using adb:
 
adb install -r <objdir-droid>/dist/fennec-*.apk
 
The installed app will be named "Fennec".
 
== Testing  ==
==== Device Managers ====
Most test suites - mochitests, reftests, xpcshell tests, and others - use a "device manager" module to communicate with the remote device. There are two device manager implementations: ADB and SUT.
 
The ADB device manager uses the adb command from the Android SDK to communicate with the remote device. To use the ADB device manager:
* ensure the adb command is in your shell's PATH
* set environment variable DM_TRANS=adb
 
The SUT device manager uses TCP to communicate with a remote agent, which must be installed on the device. To use the SUT device manager:
* ensure TCP connectivity between the local host and the remote device: check that they are on the same network and you can ping each from the other
* ensure the SUT agent is installed and started on the remote device
* set environment variable DM_TRANS=sut
* set environment variable TEST_DEVICE=<ip address of remote device -- displayed by SUT agent>
 
==== Host Builds (MOZ_HOST_BIN) ====
Android mochitests and reftests require a parallel host build -- a build for the local host (desktop) environment. An environment variable, MOZ_HOST_BIN, must be set to point to that host build. MOZ_HOST_BIN is used to run xpcshell (for instance, to provide a simple web server), so the MOZ_HOST_BIN directory must contain xpcshell and all the shared libraries required by xpcshell. You can patch together these files from other sources, but the easiest way to get these is to build Firefox for desktop and set MOZ_HOST_BIN=<objdir-x86>/dist/bin.
 
A desktop mozconfig might be as simple as:
 
  ac_add_options --enable-application=browser
  mk_add_options MOZ_OBJDIR=./objdir-x86
 
Then execute:
 
  export MOZCONFIG=mozconfig.x86
  make -f client.mk
  MOZ_HOST_BIN=objdir-x86/dist/bin
  ls -l $MOZ_HOST_BIN/xpcshell
 
On Linux, the path to that build may also need to be in your LD_LIBRARY_PATH, unless your LD_LIBRARY_PATH contains ".":
 
  LD_LIBRARY_PATH=$LD_LIBRARY_PATH:.
 
==== Test Directory ====
We currently make the assumption that the device has a mounted sdcard when running tests (see {{bug|683895}}). If, and only if, you can't mount an sdcard for whatever reason run:
 
  mkdir /data/local/tests
 
=== Reftests  ===
 
  MOZ_HOST_BIN="<abspath-to-objdir-x86>/dist/bin/" make -C <objdir-droid> reftest-remote
 
For devices with screens too small you will see the error |can't drawWindow remote content|. You can ignore that resolution requirement by using the |ignore-window-size| options. NOTE: This may lead to false negative/positives.
 
  EXTRA_TEST_ARGS="--ignore-window-size"
 
=== Mochitests  ===
 
  MOZ_HOST_BIN="<abspath-to-objdir-x86>/dist/bin/" TEST_PATH=<path> make -C <objdir-droid> mochitest-remote
 
Note that as of this writing (September 2011) many mochitests will not complete successfully. Try setting your TEST_PATH to "dom/tests/mochitest/dom-level1-core" or "content/smil/test" if you want to restrict yourself to a subset of tests that are known to pass.
 
TEST_PATH can be:
content/smil/test
content/xml/document/test
content/xslt/tests/mochitest
dom/src/json/test
dom/src/jsurl/test
dom/tests/mochitest/dom-level0
dom/tests/mochitest/dom-level1-core
dom/tests/mochitest/dom-level2-core
dom/tests/mochitest/ajax/mochikit
dom/tests/mochitest/ajax/scriptaculous
dom/tests/mochitest/ajax/jquery
dom/tests/mochitest/dom-level2-html
Harness_sanity
editor/composer/test
intl/uconv/tests
dom/tests/mochitest/orientation
dom/tests/mochitest/storageevent
layout/xul/test
modules/libjar/test/mochitest
layout/inspector/tests
toolkit/xre/test
toolkit/components/microformats/tests
MochiKit-1.4.2/tests
parser/htmlparser/tests/mochitest
js
 
Notes:
* A rooted device MAY be required (under investigation).
* ADB or SUT device manager may be used.
 
=== Robotium ===
 
The Robotium / Robocop test suite verifies UI behavior in native Fennec.
 
Build and install native Fennec, then execute the mochitest-robotium make target.
 
  make -f client.mk
  cd <objdir>
  make package
  adb install -r dist/fennec-12*.apk
  MOZ_HOST_BIN="<abspath-to-objdir-x86>/dist/bin/" make mochitest-robotium
 
More info at https://wiki.mozilla.org/Auto-tools/Projects/Robocop.
 
Notes:
* A rooted device is NOT required.
* ADB device manager is used by default; SUT is also supported.
* MOZ_HOST_BIN is used to launch xpcshell on the desktop to provide a web server.
* Use TEST_PATH=<test-name> to run just one test at a time.
 
=== xpcshell  ===
 
To prepare your device for xpcshell tests:
 
  adb shell mkdir /data/local/tests
 
Also be sure you have successfully built Fennec and generated an APK, as described above.
 
To run all tests referenced by the master xpcshell manifest:
 
  cd <objdir-droid>
  make xpcshell-tests-remote
 
To run a subset of tests in the specified directory:
 
  make -C <test-directory> xpcshell-tests-remote
 
Once either of the xpcshell-tests-remote commands has completed successfully, all test files have been copied to device, and it is then possible to run a single test quickly, without setup:
 
  make SOLO_FILE=<test-file> -C <test-directory> check-one-remote
 
Notes:
* A rooted device IS required.
* ADB device manager is used by default. SUT is not yet supported.
* The test root directory cannot be on /sdcard -- it must be /data/local so that +x permissions can be set on xpcshell.
 
=== browser-chrome ===
 
Before you run tests, you will need to make sure you have packaged the tests in your object dir:
 
  make -C <objdir-droid> package-tests
 
There is currently no special make command to build and run browser-chrome tests, but it should be possible to make them run by calling:
 
  cd <objdir-droid>/_tests/testing/mochitest
  python runtestsremote.py --dm_trans=adb --test-path=mobile --browser-chrome --deviceIP=1.2.3.4
                          --app=org.mozilla.fennec_$USER --xre-path=<objdir_x86>/dist/bin/
 
=== talos ===
 
*NOTE: this requires python 2.5 or greater (tested up to 2.7)
 
See https://wiki.mozilla.org/Buildbot/Talos
 
This is 100% out of band from mozilla-central (same for desktop also).
 
  hg clone http://hg.mozilla.org/build/talos talos
  cd talos
  python INSTALL.py
  . bin/activate
  cd talos
 
Run these commands to check out the talos dependencies (assuming you are already in the "talos/talos" directory):
 
  cd page_load_test
  wget http://people.mozilla.org/~jmaher/mobile_tp4.zip
  unzip mobile_tp4.zip
 
Configure a talos profile. You can do this via adb or [http://people.mozilla.com/~bmoss/SUTAgent/ SUTAgent] - if you want to use adb make sure you have rooted your device such that "adb shell" goes directly into a root shell. If you want to use adb to communicate with the device remotely, do something like this:
 
  python remotePerfConfigurator.py -v -e org.mozilla.fennec --develop --activeTests tpan --output tpan.yml --remotePort -1
 
If you want to use [http://people.mozilla.com/~bmoss/SUTAgent/ SUTAgent] to communicate with the device, do something like this:
 
  python remotePerfConfigurator.py -v -e org.mozilla.fennec --develop --activeTests tpan --output tpan.yml --remoteDevice <ip of your sutagent>
 
SUTAgent will not be able to read the application.ini on the device, so you will need to copy it. We highly recommend pulling the application.ini from the .apk and copying it to the talos/talos/remoteapp.ini file. 
 
Unless two applications are signed with the same key they cannot read each others' /data/data directories, so SUTAgent cannot read org.mozilla.fennec's data directory.
You can extract it from the fennec .apk or get it from adb from e.g. /data/data/org.mozilla.fennec/application.ini
 
  shell@android:/ $ su
  shell@android:/ # cat /data/data/org.mozilla.fennec/application.ini
  [App]
  Vendor=Mozilla
  Name=Fennec
  Version=10.0a1
  BuildID=20111031031100
  SourceRepository=http://hg.mozilla.org/mozilla-central
  SourceStamp=04b4ea333800
  ID={a23983c0-fd0e-11dc-95ff-0800200c9a66}
 
  [Gecko]
  MinVersion=1.9.2b5pre
  MaxVersion=10.0a1
 
  [XRE]
  EnableExtensionManager=1
 
  [Crash Reporter]
  Enabled=1
  ServerURL=https://crash-reports.mozilla.com/submit
 
Finally, run talos:
 
  python run_tests.py -d -n tpan.yml
 
'''Note''': As of this writing (Sept 27, 2011), the tgfx pageset does not currently work (it isn't run on the desktop either). Don't try it. :)
 
=== Trouble-shooting testing problems ===
 
* Does your mozconfig contain "ac_add_options --disable-tests"?
** If so, you will see something like:
<pre>
make: *** No rule to make target <your-test-target>. Stop.
</pre>
* Is adb in your $PATH?
* Is your device connected? Does it appear in the output from "adb devices"?
* Can you run adb shell?
* If running xpcshell, did you create /data/local/tests?
* If running "make check-one-remote", did you first setup the device with "make xpcshell-tests-remote"?
 
== Debugging ==
 
=== Using logcat ===
 
[http://developer.android.com/guide/developing/tools/logcat.html logcat] is a tool that is going to show you some logs prompted by the device. It might be a good help if you don't want to or can't run gdb. You can use it by running this command:
 
  adb logcat
 
You can make things appear in logcat using printf_stderr. With debug builds, NS_WARNING, NS_ERROR and NS_ASSERTIONS will show up in logcat. A good idea is to actually run
 
  adb logcat -v time
 
so that the log includes timestamps for events. If you're trying to debug something, you may wish to pipe the logcat output through grep to filter out irrelevant things (most Fennec-related output will be viewable by "adb logcat | grep Gecko"), but remember that when attaching log output to a bug you should include unfiltered output as there may be relevant log entries under other tags. Additional tips on how to use adb logcat can be found at http://aaronmt.com/?p=503
 
==== Using aLogCat ====
 
If you don't have the Android SDK installed, you can still extract logs using an application called aLogCat. Install it from the Android Market. Use it to capture logs and attach the logs to bugs.
 
https://market.android.com/details?id=org.jtb.alogcat&hl=en
 
Once you have alogcat installed, just use Fennec as you would normally. Upon encountering a bug or issue, start the aLogcat app (as soon as possible after seeing the Fennec issue) and select "Share" or "Save" from the menu to send it via email or save it to the SD card. The log can then be attached to a bug or sent to a developer. As with adb logcat, it is better to have a log with timestamps than without timestamps. To enable timestamps in the log, select "Preferences" from the aLogcat menu, and change the "Format?" option to "Time".
 
If you need to, you can search for some kinds of Fennec-related output by using the "Filter" menu item and entering "Gecko". However, when submitting logs for bug reports, please make sure you clear the filter and include all of the available log data.
 
==== JavaScript dump() ====
 
To use the dump() function in JavaScript to write to the log:
 
# Go to about:config and set browser.dom.window.dump.enabled to "true"
# Run the following ADB commands:
 
adb shell stop
adb shell setprop log.redirect-stdio true
adb shell start
 
=== Using nVidia GDB ===
 
Nvidia's gdb is better: http://developer.download.nvidia.com/tegra/files/tegra-gdb-20100902.zip
You probably want to use JimDB instead of Nvidia's gdb
 
=== Using JimDB ===
* jchen has been working on a better Android gdb ('jimdb'). [https://github.com/darchons/android-gdb source], and [[Mobile/Fennec/Android/GDB|build instructions]]. For best results, rebuild everything. [http://www.jnchen.com/_media/projects/mozilla/moz-gdb.tar.bz2 Prebuilt binaries] are available but problems with them have been reported.
** has most fixes from NDK gdb
** integrates Android libthread_db (fixed dougt's problem debugging threads)
** has Python scripting support
** [https://github.com/darchons/android-gdbutils couple of existing Python scripts] (or if using prebuilt binaries above, just run 'git pull' under the 'utils' directory)
*** feninit is a tool to initialize the GDB environment (support for multiple devices, multiple object directories; launches Fennec, pulls libraries, sets paths, and attaches gdbserver automatically)
*** tracebt is a WIP stack unwinder that traces instructions to find stack frames
*** idea for another tool to parse and integrate logcat into gdb
*** other ideas welcome!
* see [[Mobile/Fennec/Android/GDB]] for installation instructions
 
=== Using Debug Intent ===
In order to attach before things get running, launch with (replace "unofficial" with your login name):
 
  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 [http://dump.lassey.us/debug.sh] will attach gdbserver for you
 
=== Getting dalvik java stack dumps using gdb ===
 
(gdb) call handleSigQuit()
 
this will dump a stack trace to gDvm.stackTraceFile which defaults to "/data/anr/traces.txt"
 
=== Arguments and Environment Variables ===
 
If you need to set an environment variable at run time, 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_<user>/.App --es env0 VAR=val --es env1 FOO=bar
 
If you need to pass arguments at run time, append '''--es args "<your-args>"''' to your activity manager command. For example, to launch with a specific profile:
 
  adb shell am start -a android.activity.MAIN -n org.mozilla.fennec_<user>/.App --es args "--profile /mnt/sdcard/myprofile"
 
To launch with a specific URL, use the am -d option to set the intent's data URI:
 
  adb shell am start -a android.activity.MAIN -n org.mozilla.fennec_<user>/.App -d 'http://www.mozilla.org'
 
=== PR Logging ===
 
You can use the env vars as described above to enable NSPR logging:
 
  adb shell am start -a android.activity.MAIN -n org.mozilla.fennec_<user>/.App --es env0 NSPR_LOG_MODULES=all:5 --es env1 NSPR_LOG_FILE=/mnt/sdcard/log.txt
 
If no file is specified, logging is directed to the android logs:
 
  adb shell am start -a android.activity.MAIN -n org.mozilla.fennec_<user>/.App --es env0 NSPR_LOG_MODULES=all:5
 
Look for lines marked "PRLog" in the adb logcat output.
 
=== 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
 
The above will miss some vendor drivers, you can use busybox to find all shared libraries
 
for file in $(adb shell /data/local/busybox find / -name "*.so" | tr "\n" " " | tr "\r" " "); do  adb pull /$file lib_unlock_nexus/; done
 
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 [&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
 
=== Attaching GDB ===
Assuming you have the nvidia gdb at the top of your home directory and the app_process binary in the current working directory.
  ~/nvidia-gdb/prebuilt/linux-x86/arm-eabi-gdb ./app_process
 
== 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. Note that putting a ''.gdbinit'' file inside a directory will make gdb load it thus you will not pollute your regular gdb init with those configurations.
 
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
 
=== Connecting Eclipse to Android Build tree ===
 
Clone scripts and templates:
  hg clone http://hg.mozilla.org/users/romaxa_gmail.com/eclipse_mobile
  cd eclipse_mobile
 
Modify mozconfig_values file, according to your build environment
add absolute path to obj-build-dir and source dir, Ex:
  MOZOBJDIR=/home/romaxa/mozdev/mozillahg/mozilla-birch/objdir-droid
  MOZSRCDIR=/home/romaxa/mozdev/mozillahg/mozilla-birch
 
Generate project content (build tree must be fully compiled and make -C objdir package commands performed):
  run ./create_projects.pl
  eclipse project will be created in current folder
 
Create new project in Eclipse
  File->New->Project
  Android Project
  Next, Create project from existing source
  Select current folder as Location, Next
  Select Build Target "Android 3.2 / API 13"
  Next and Finish
 
Press Run App button in order to perform first build,
*
  On first run, some ADT plugin fnctionality removing bin/App.apk and resource.ap_)
  Don't know how to teach eclipse don't do that, but it breaks installable package.
  So in order to fix that problem
  after first Run App, execute in project folder
    ./fixup_links.pl
  It will update *.apk and *.ap_ symlinks
 
Press Run App button again
 
try to setup breakpoint in onCreate() and press Debug App button.
 
=== Rooting Android devices ===
 
See [[Mobile/Fennec/Android/Rooting|Rooting Android Devices]].

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"