Mobile/Fennec/Android

The Fennec build documentation has moved!
See the most up to date documentation at https://developer.mozilla.org/en-US/docs/Simple_Firefox_for_Android_build

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 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 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.

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
ac_add_options --with-android-min-sdk=14

# 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 $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

During ./mach build if you get an error that looks like this:

/path/to/mozilla-central/obj-x86_64-unknown-linux-gnu/Makefile Error 2

It means you're trying to build for Desktop, the reason might be that the build script can't see your mozconfig file. You can fix this by running |mach build| again after exporting a MOZCONFIG environment variable.

export MOZCONFIG=/path/to/mozilla-central/mozconfig
./mach build

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.

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 mach mercurial-setup and installed the mozext tools when prompted.

1. Add the following to your mercurial config file .hg/hgrc 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 nalexander's blog post introducing mach artifact.

Building with mach artifact

When building, you need to run an extra mach artifact 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 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

The Fennec build system requires the following versions:

• Android SDK Platform Android 6.0 (API 23)
• SDK Build Tools 23.0.1 or later
• SDK Platform Tools 23.0.1 or later
• Android SDK Tools 23.0.1 or later
• Android Support Repository 21 or later
• Google Repository 22 or later

If your build fails because you're missing one of the Android or Google requirements, your first step should be to run the mach bootstrap. If you don't want to run the bootstrapper, you can manually install by running the Android SDK manager: try mach android, or $ANDROID_SDK/tools/android.

bug 1207680 tracks listing these version requirements in one place in the source code.

Learn more

• Common Tips and How-To's
• Testing
• Distribution Files
• Mercurial for Mozilla development
• Advanced Topics