Mobile/Fennec/Android
Building Fennec
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.
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.
Getting the source
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.)
hg clone http://hg.mozilla.org/mozilla-central/
The source files will be in the mozilla-central directory, which we refer to as your source directory.
Now run the setup script, which will walk you through the setup:
./mach bootstrap
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).
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 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 install and configure Mercurial as described here. Mercurial is a very powerful 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. 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). The mozconfig file is what tells the Mozilla build system what to build and how your build environment is prepared.
It should be named mozconfig in your source directory, as the build scripts will read from the mozconfig file in your source directory by default, although you can configure this if you need to.
Here is a minimal mozconfig file (you will need to fill out the paths):
# 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 $HOME instead of ~ in your mozconfig because ~ 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, 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 objdir-droid/dist folder, and will be called something like fennec-28.0a1.en-US.android-arm.apk. You can install this APK to your device manually using adb install or ./mach install.
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 mobile/android directory using ./mach build mobile/android or ./mach build mobile/android/base, 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 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" | here, or jump into #mobile to ask.
These 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 mach mercurial-setup when cloning the source code repository -- this will ensure you have good default settings and extensions.
Instructions for submitting a patch can be found here. If you have already applied for level 1 commit access, be sure to check out MozReview.
After writing the patch, make sure the commit message is of the correct format:
Bug <bug#> - <bug title>. r=<reviewer>
So for example, for bug 1128431, the commit message should be:
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 Mercurial patch queues.
If you're interested in using bookmarks, take a look at bookmarks-based development.
(If you want more information about bookmarks-based workflow, take a look at gps's slides; 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 Mercurial for Mozillians. Also, if you're curious to see an active hgrc with potentially useful aliases (and thus commonly used commands), check here.
Additional topics
For information on how to run and write tests, see the Testing page.
For more specialized topics, see these Advanced Topics. You can find information about advanced debugging, modifying build flags, etc.
Troubleshooting
For if you're running into trouble building.
Android NDK and SDK version notes
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 in this mailing list posting. If you are seeing the following build error then you will need to 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 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.