Mobile/Fennec/Android: Difference between revisions

From MozillaWiki
< Mobile‎ | Fennec
Jump to navigation Jump to search
(Fix link to current build doc)
 
(33 intermediate revisions by 10 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 set up Mercurial with reasonable defaults (patch defaults, etc).
./mach mercurial-setup
 
==== 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
 
Or, if you have wget installed instead:
 
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. Once you have all the dependencies installed, you will need to clone the Firefox repository.
 
=== Preparing a Fennec mozconfig ===
 
Next, navigate to your source directory and create a text file called "mozconfig". The bootstrap script will print out the contents of mozconfig for you when it finishes (and you can run the script again to print this information out). 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].
 
This is what a minimal mozconfig would look like:
 
# 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"
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.
 
==== Building faster with 'mach artifact' ====
Since most Firefox for Android development is in Java and JS, you can speed up your build process by downloading rather than building the C++ code pieces, because that takes up the majority of build time. This is optional and not necessary for developing on Firefox for Android, so you can skip this section and do it later if you wish.
 
===== mach artifact setup =====
Make sure that you have run <tt>mach mercurial-setup</tt> and installed the <tt>mozext</tt> tools when prompted.
 
1. Add the following to your mercurial config file <tt>.hg/hgrc</tt> in your source directory.
[extensions]
mozext = /PATH/TO/HOME/.mozbuild/version-control-tools/hgext/mozext
 
2. Mirror a local copy of the pushlog with:
hg pushlogsync
Mercurial should show a long (and slow) progress bar. From now on, each time you hg pull, you’ll also maintain your local copy of the pushlog.
 
3. Add the following lines to your mozconfig:
ac_add_options --disable-compile-environment
mk_add_options MOZ_OBJDIR=./objdir-frontend
(The objdir can be whatever you choose, but it's named differently so you can go back to non-artifact building if you choose.)
 
And that's all!
 
For more detailed explanations of these steps, see [http://www.ncalexander.net/blog/2015/07/02/build-fennec-frontend-fast-with-mach-artifact/ nalexander's blog post] introducing mach artifact.
 
===== Building with mach artifact =====
When building, you need to run an extra <tt>mach artifact</tt> step:
./mach build
./mach artifact install
./mach package
./mach install
 
NOTE: This will not pick up C++ changes so if you are changing those files, you will have to use the original mozconfig method of building.
 
=== 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 />
Bug 1128431 -  'Start browsing' link from onboarding v1.5 is not visible on small screen devices. r=liuche
 
=== Mercurial and Workflow ===
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.
 
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].
 
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].
 
(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.)
 
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].


=== Additional topics ===
=== App and development overview ===
For information on how to run and write tests, see the [[Mobile/Fennec/Android/Testing|Testing]] page.
* [[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.


For more specialized topics, see these [[Mobile/Fennec/Android/AdvancedTopics|Advanced Topics]]. You can find information about advanced debugging, modifying build flags, etc.
=== 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]]


== Troubleshooting ==
=== Test results ===
For if you're running into trouble building.
*[https://scan.coverity.com/projects/firefox-mobile Coverity static analysis]


=== Android NDK and SDK version notes ===
=== Build infrastructure ===
*[[Mobile/Fennec/Android/Task Cluster notes|Task Cluster notes]]
*[[Mobile/Fennec/Android/mach_bootstrap_SDK_dependencies|`./mach bootstrap` SDK dependencies]]


The Fennec build system requires the following versions:
=== 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]


* Android SDK Platform '''Android 5.1.1 (API 22)'''
=== Crash Stats ===
* SDK Build Tools '''22.0.1''' or later
* The crash-stats page lives at https://crash-stats.mozilla.com/home/product/FennecAndroid
* SDK Platform Tools '''22.0.1''' or later
** Be careful to select "'''FennecAndroid'''" under the product dropdown to see Firefox on Android crashes.
* Android SDK Tools '''22.0.1''' or later
*** Nightly has the name XX.0a1 (e.g. 52.0a1)
* Android Support Repository '''20''' or later
*** Aurora has the name XX.0a2 (e.g. 51.0a1 - the number is one lower than nightly)
* Google Repository '''22''' or later
*** 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.
If your build fails because you're missing one of the Android or Google requirements, your first step should be to run the <tt>mach bootstrap</tt>. If you don't want to run the bootstrapper, you can manually install by running the Android SDK manager: try <tt>mach android</tt>, or <tt>$ANDROID_SDK/tools/android</tt>.
*** 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.
{{bug|1207680}} tracks listing these version requirements in one place in the source code.
** 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.
== Learn more ==
*[[Mobile/Fennec/Android/CommonTips|Common Tips and How-To's]]
*[[Mobile/Fennec/Android/Testing|Testing]]
*[https://mozilla-version-control-tools.readthedocs.org/en/latest/hgmozilla/index.html Mercurial for Mozilla development]
*[[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"