Mobile/Fennec/Android: Difference between revisions

From MozillaWiki
< Mobile‎ | Fennec
Jump to navigation Jump to search
(Fix link to current build doc)
 
(55 intermediate revisions by 12 users not shown)
Line 1: Line 1:
== Building Fennec ==
{{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}}


'''Right now it is possible to build Fennec on most UNIX-like systems, including Mac OS X and many flavors of Linux.'''  Most core developers run Mac OS X; a handful run Linux.
Here is a table of contents of all the in-depth information you might need to find about Firefox for Android development.


'''Sadly we do not yet support building Fennec on Microsoft Windows'''.  We know of no strong reason that it should not be possible (now; in the past, it was not possible because Google did not release certain parts of the Android toolchain for Windows), but it's also not a priority.  If you're interested in building on Windows, or can contribute, please CC yourself onto {{bug|1169873}}.
New to the community? Welcome! [[Mobile/Get_Involved|Start here!]]


=== Getting the source ===
== Develop ==
 
*[[Mobile/Get Involved|New contributor page]]
First, grab a clone of the Fennec source code repository. (If you don't have mercurial installed, install that, or you can run the setup script directly by following the instructions in the following section.)
**[[Mobile/Fennec/Android/Suggested workflow|Suggested workflow]]
 
*[https://developer.mozilla.org/en-US/docs/Simple_Firefox_for_Android_build Build documentation]
hg clone http://hg.mozilla.org/mozilla-central/
*[[Mobile/Fennec/Android/Testing|Testing]]
 
*[[Mobile/Fennec/Android/CommonTips|Common tips & how-to's]]
The source files will be in the <tt>mozilla-central</tt> directory, which we refer to as your ''source directory''.
*[[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)]]
Now run the setup script, which will walk you through the setup:
*[[Mobile/Fennec/Android/AdvancedTopics|Advanced topics (e.g. special build configs & advanced debugging)]]
  ./mach bootstrap
*[https://gecko.readthedocs.org/en/latest/mobile/android/fennec/index.html In-tree Firefox for Android documentation]
 
*[[Mobile/Triage|Triage]]
Choose to build "Firefox for Android" at the prompts.  This will help you install all the build prerequisites required for building Fennec on the most popular host operating systems (including OS X and Debian-flavoured Linuxes, including Ubuntu; but sadly not including Windows).
*[[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.
You may need an hour or more to download and install dependencies (Java, the Android SDK and NDK, and the Android platform itself, are very large).  You may be prompted to enter your password or to accept license agreements.
 
NOTE: If that doesn't work, or you need more details: Follow the [https://wiki.mozilla.org/Mobile/Fennec/Android/Detailed_build_instructions detailed instructions to set up a build environment] on your machine. Once you have done that, follow the steps to get the source, set up your mozconfig, and build Fennec.
 
Before doing anything else, it's a good idea to [https://mozilla-version-control-tools.readthedocs.org/en/latest/hgmozilla/index.html install and configure Mercurial as described here]. Mercurial is a very powerful (but oft-misunderstood) version control tool, but it has painful defaults.
 
=== Alternative: Run the setup script directly ===
 
Run either of the following in a terminal.  If you have curl installed (note that Mac OS X ships curl by default):
 
curl -O https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py && python bootstrap.py
 
If you have wget installed:
 
wget -q https://hg.mozilla.org/mozilla-central/raw-file/default/python/mozboot/bin/bootstrap.py && python bootstrap.py
 
Then go back and follow the directions as if you had launched the setup script by downloading the source. You will need to clone the repository later with
 
  hg clone http://hg.mozilla.org/mozilla-central/
 
=== Preparing a Fennec mozconfig ===
 
Next, navigate to your source directory and create a text file called "mozconfig". The mozconfig file is what tells the Mozilla build system what to build and how your build environment is prepared. Here is the minimal mozconfig file for building Fennec; it should be named <tt>mozconfig</tt> in your source directory, as the build scripts will read from the mozconfig file in your source directory by default, [https://developer.mozilla.org/en-US/docs/Configuring_Build_Options although you can configure this if you need to].
 
# Build Firefox for Android:
ac_add_options --enable-application=mobile/android
ac_add_options --target=arm-linux-androideabi
# With the following Android SDK and NDK:
ac_add_options --with-android-sdk="/path/to/android-sdk/platforms/android-22"
ac_add_options --with-android-ndk="/path/to/android-ndk-r10e"
 
This assumes you have followed the instructions above and are using Android platform 22 and NDK version r10e.  You must use <tt>$HOME</tt> instead of <tt>~</tt> in your mozconfig because <tt>~</tt> does not get expanded.
 
Mozilla's build system writes all build intermediate files and output artifacts into a separate directory called the ''object directory''. The build system will choose a reasonable default name for the object directory if you don't specify one, but it's common to specify an object directory starting with "obj" and to put it inside your source directory.  Add a line like the following to your mozconfig:
 
mk_add_options MOZ_OBJDIR=./objdir-droid
 
=== Building and deploying the Fennec Android package ===
 
Before you start building, [http://developer.android.com/guide/developing/device.html connect your Android device and enable USB debugging].
 
The following steps will build Fennec (compile and link all C/C++, Java, and JavaScript source code), prepare a fresh Fennec APK, and deploy Fennec to your Android device:
 
./mach build
./mach package
./mach install
 
The APK file can be found in your <tt>objdir-droid/dist</tt> folder, and will be called something like <tt>fennec-28.0a1.en-US.android-arm.apk</tt>. You can install this APK to your device manually using <tt>adb install</tt> or <tt>./mach install</tt>.
 
The name of the app that shows up on your phone will be "Fennec $USER" (where $USER is the username under which you built the code).
 
To speed up subsequent builds you should build only part of the <tt>mobile/android</tt> directory using <tt>./mach build mobile/android</tt> or <tt>./mach build mobile/android/base</tt>, depending on where your changes are.
 
=== Developing Fennec with IDEs ===
 
Fennec has support for developing using IntelliJ (Ultimate and Community Edition) and Android Studio.  (We also have some legacy support for Eclipse, but you should prefer using IntelliJ or Android Studio.)  Get started [[/IDEs|Developing Fennec with IDEs]].
 
== Contributing Code ==
Congratulations, now you've got a build set up! Now you can start contributing code.
 
If you're a new contributor, you can pick a "good first bug" [http://www.joshmatthews.net/bugsahoy/?mobileandroid=1&unowned=1&simple=1 | here], or jump into #mobile to ask.
 
These [[Mobile/Fennec/Android/CommonTips|common Tips and How-To's]] will help you get started.
 
=== Creating commits and submitting patches ===
Mercurial (hg) is the the main version control system that Mozilla uses, and to submit code for review, you should be able to generate patches or commits. Be sure to run <tt>mach mercurial-setup</tt> when cloning the source code repository -- this will ensure you have good default settings and extensions.
 
Instructions for submitting a patch can be found [https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/How_to_Submit_a_Patch#Committing_the_patch here]. If you have already applied for level 1 commit access, be sure to check out [http://mozilla-version-control-tools.readthedocs.org/en/latest/mozreview/install.html MozReview].
 
After writing the patch, make sure the commit message is of the correct format:<br />
Bug <bug#> - <bug title>. r=<reviewer>


So for example, for [https://bugzilla.mozilla.org/show_bug.cgi?id=1128431 bug 1128431], the commit message should be:<br />
=== App and development overview ===
Bug 1128431 -  'Start browsing' link from onboarding v1.5 is not visible on small screen devices. r=liuche
* [[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.


=== Mercurial and Workflow ===
=== Feature development ===
Historically, Mozilla has used Mercurial patch queues to submit code changes for review. However, Mozilla developers are now encouraged to use a Mercurial bookmark-based workflow.
* [[Mobile/Distribution_Files|Distribution files]]
* [[Mobile/Fennec/Android/Java_telemetry|Java telemetry]]
* [[Mobile/Fennec/Android/Switchboard|Switchboard]]
* [[Mobile/Fennec/Android/Downloadable_Content|Downloadable Content]]


If you're a contributor and new to Mercurial, patch queues are conceptually simple and fine for getting your first few patches up; see the instructions on [https://developer.mozilla.org/en-US/docs/Mercurial_Queues Mercurial patch queues].
=== Test results ===
*[https://scan.coverity.com/projects/firefox-mobile Coverity static analysis]


If you're interested in using bookmarks, take a look at [http://mozilla-version-control-tools.readthedocs.org/en/latest/hgmozilla/bookmarks.html bookmarks-based development].
=== Build infrastructure ===
*[[Mobile/Fennec/Android/Task Cluster notes|Task Cluster notes]]
*[[Mobile/Fennec/Android/mach_bootstrap_SDK_dependencies|`./mach bootstrap` SDK dependencies]]


(If you want more information about bookmarks-based workflow, take a look at gps's [https://people.mozilla.org/~gszorc/mastering-vcs/#1 slides]; [http://gregoryszorc.com/blog/category/mercurial/3/ gps's blog] is another good place to get information about version control at Mozilla.)
=== 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]


For more information about configuring your hg environment to work well at Mozilla, see [http://mozilla-version-control-tools.readthedocs.org/en/latest/hgmozilla/index.html Mercurial for Mozillians]. Also, if you're curious to see an active hgrc with potentially useful aliases (and thus commonly used commands), check [https://github.com/mcomella/dotfiles/blob/master/hg/hgrc here].
=== Crash Stats ===
 
* The crash-stats page lives at https://crash-stats.mozilla.com/home/product/FennecAndroid
=== Additional topics ===
** Be careful to select "'''FennecAndroid'''" under the product dropdown to see Firefox on Android crashes.
For information on how to run and write tests, see the [[Mobile/Fennec/Android/Testing|Testing]] page.
*** 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)
For more specialized topics, see these [[Mobile/Fennec/Android/AdvancedTopics|Advanced Topics]]. You can find information about advanced debugging, modifying build flags, etc.
*** 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.
== Troubleshooting ==
*** 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.
For if you're running into trouble building.
** 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.
=== Android NDK and SDK version notes ===
** 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.
 
Members of the Fennec community are successfully building Fennec with:
 
* Android SDK Platform '''Android 5.1.1 (API 22)'''
* SDK Build Tools '''22.0.1'''
* SDK Platform Tools '''22'''
* Android SDK Tools '''24.3'''
* Android Support Repository '''15'''
* Android Support Library '''22.2'''
* Google Play Services '''25'''
* Google Repository '''19'''
 
'''2015/08/26 "Support library 23 and SDK 22/23"''': Currently the latest support library version available is 23. This version requires you to build with SDK 23 but Fennec does not build with that SDK version just yet. You can find more about that [https://mail.mozilla.org/pipermail/mobile-firefox-dev/2015-August/001399.html in this mailing list posting]. If you are seeing the following build error then you will need to [https://mobile.etherpad.mozilla.org/109 manually downgrade your support library to version 22]:
 
    /usr/local/opt/android-sdk/extras/android/support/v7/appcompat/res/values-v23/styles_base.xml:20: error:
    Error retrieving parent for item: No resource found that matches the given name 'android:Widget.Material.Button.Colored'.
    /usr/local/opt/android-sdk/extras/android/support/v7/appcompat/res/values-v23/styles_base_text.xml:19: error:
    Error retrieving parent for item: No resource found that matches the given name 'android:TextAppearance.Material.Widget.Button.Inverse'.
 
 
"Google Play Services" is listed under Extras by the ''android'' package manager.
 
You should ensure that the Support Library and SDK versions match. If you update the Support Library but don't switch to a later SDK, you'll get errors that mention a newer version than your SDK, like this:
 
  Warning: android.support.v4.view.accessibility
  .AccessibilityNodeInfoCompatApi22: can't find referenced method
  'void setTraversalAfter(android.view.View,int)' in class
  android.view.accessibility.AccessibilityNodeInfo
 
In the event that the NDK and SDK versions listed here are out of date, you can always find the [http://hg.mozilla.org/mozilla-central/annotate/tip/mobile/android/config/mozconfigs/common canonical version numbers that Mozilla uses to build Fennec in automation].  Look for the following variables:
 
* ANDROID_NDK_VERSION
* ANDROID_NDK_VERSION_32BIT
* ANDROID_SDK_VERSION
 
{{bug|1108782}} tracks listing and enforcing these version requirements in the source code.
 
== Learn more ==
*[[Mobile/Fennec/Android/CommonTips|Common Tips and How-To's]]
*[[Mobile/Fennec/Android/Testing|Testing]]
*[[Mobile/Fennec/Android/AdvancedTopics|Advanced Topics]]

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"