Deprecated: This documentation is out of date, please visit geckoview-quick-start for up-to-date documentation on building GeckoView for Android.
This page covers the basic steps needed to build a bleeding-edge, development version of Firefox for Android, also known as Fennec. Welcome, we're delighted to see you! :)
If you're having trouble following this documentation or hit a roadblock you can't get around, please contact Nick Alexander at firstname.lastname@example.org directly so we can solve the problem for you and every new contributor after you.
Building Firefox for Android on Microsoft Windows requires Windows 10 Creator Update or later. From Firefox 58, you can build Firefox for Android using Windows under Windows Subsystem for Linux (WSL, Bash on Windows). If using WSL, please use same way like Linux. But, since it is still unstable, we don't recommend that you use WSL to build Firefox for Android. Also, Android Studio doesn't still support on Windows even if under WSL.
Prepare your development environment
To start hacking on Fennec — the code name for Firefox for Android — you’ll need three things:
- A computer (or Virtual Machine) running Linux or OSX with 30Gb of free space.
- An Android device to test it on.
- A reasonably fast internet connection.
The computer needs to be running a 64-bit Unix-based OS. You can make sure your OS is 64-bit by opening a terminal window, typing:
and hitting enter. If you see
"x86_64" your computer is ready to go.
Fennec will run almost all Android phones made in the last four years. Older phones — those using ARMv6 chips or earlier — won’t work, but any recent phone will.
If you have your phone and computer to hand, let’s get started!
Setting up your Android device
Getting your Android device ready for development is fast and easy:
- In the Settings menu, choose "About" and scroll down to the Build Number option.
- There's a hidden option there to activate "developer mode": tap the Build Number option seven times. You’ll see a countdown, and then a "Developer Options" menu will appear in your Settings. Don’t worry — you can turn this off whenever you like.
- The last step is to enable USB Debugging in the Developer Options menu.
This section lists the hardware requirements for buiding Fennec:
- A decent speed CPU. While you can build Firefox on older hardware, it can take quite a bit of time to compile on slower machines. Having at least 8GB of RAM is recommended, preferably more if you do full builds and also want to keep Android Studio open at the same time. If you have older hardware, it is strongly recommended that you use artifact mode.
- Fast broadband internet is strongly recommended as well. Both the development environment, and the source code repository, are quite large. Artifact mode regularly downloads large (50MB) binary archives.
- You must have a 64-bit operating system. As of early 2015 it is no longer possible to build Firefox on most 32-bit machines.
- If you're going to install Firefox for Android on a physical Android device, you'll need one running Android Jelly Bean (API 16) or later.
- You can also develop against an emulator; see MozillaWiki for more details. All the
machcommands discussed on this page should work with an emulated Android device the same as on physical hardware.
Get the source
Get the latest source code from Mozilla's Mercurial code repository. This may take a while; it's a lot of code!
If your Mercurial version is < 1.5 we recommend that you add the progress extension to your Mercurial configuration. This will provide feedback during the lengthy clone process. See the documentation explaining how to enable the Mercurial progress extension.
hg clone https://hg.mozilla.org/mozilla-central
If you are using a slow or unreliable internet connection,
hg clone might fail if it gets interrupted. In that case, you are strongly encouraged to download a Mercurial bundle file instead of waiting for
1. bootstrap also has a Rust dependency, which requires it to run twice to make the env setup complete. I suggest installing Rust before you run the bootstrap once, then again a second time.
2. If you are a Mac user, you'll need to install Xcode. You'll also need to a) run sudo xcodebuild -license in your terminal or b) manually open Xcode to accept the license before you start the bootstrap process.
3. Currently Fennec doesn't support instant run. Please disable it before you use Android Studio to build/install Fennec, in File -> Settings -> Build, Execution, Deployment -> Instant run.
Run the following in a terminal from within the
mozilla-central directory you checked out earlier. You'll need Python version 2.7 or later.
Choose 3. Firefox for Android Artifact Mode when prompted (unless you already know you want to work on the back-end - in that case choose 4. Firefox for Android).
The bootstrapping script will install system packages, the Android SDK (and NDK, if required), and the currently required versions of the Android platform plus extras. If you want to know more about what Bootstrap.py is doing you can look at our detailed setup instructions. Please follow the steps in the terminal to complete the configuration. If you want to use git, when you are asked to run the Mercurial configuration wizard, you can select option 2. No.
The bootstrap script will print out configuration options for you when it finishes (more on this below). For now, copy this configuration text to a safe place and continue on. You can re-run the bootstrap script to print this information again later.
Once you have all the dependencies installed, you need to clone the Firefox repository.
Choose what parts of Firefox for Android you want to modify
Here is a table summarizing the pros and cons of working on the different parts.
|Configuration||Restrictions||Implementation languages||Build speed||Integrated development environment|
(you can use Android Studio as a fancy text editor and for debugging, though)
Do you want to modify just Firefox for Android, or do you want to modify the Gecko platform?
- I want to work on the front-end: the look and feel of Firefox for Android.
- I want to work on the back-end: Web APIs, HTML rendering or other parts of the Gecko platform.
Note: If you are not sure, start with just the Firefox for Android front-end: your build times will be much shorter if you don't build the Gecko back-end as well.
But don't worry! You can always add the back-end configuration later, and it's easy to switch between the configurations.
Prepare a Firefox for Android mozconfig file
Create a file named
mozconfig in the directory where you cloned the
mozilla-central source repository. The build scripts will read from the
mozconfig file to determine what kind of build to produce, although you can configure this if you need to. You must use
$HOME instead of
~ in your mozconfig because
~ does not get expanded.
By default, the build system creates a build of Firefox for Android roughly equivalent to the official Firefox for Android Nightly builds. If that's not exactly what you want, there are many build configuration options to choose from. It's strongly recommended that you only use options that you fully understand. Although you may already have your own Android path setup, we strongly recommended you use the version come with above steps (bootstrap.py) . This is will prevent Fennec from interfering with your original development environment.
Firefox for Android supports a fast build mode called artifact mode. (Some mobile team managers call it manager mode since it's particularly helpful if you only write code infrequently.) Artifact mode downloads pre-built C++ components rather than building them locally, trading bandwidth for time.
To use artifact mode, paste the following into your
# Build Firefox for Android: ac_add_options --enable-application=mobile/android ac_add_options --target=arm-linux-androideabi # With the following Android SDK: ac_add_options --with-android-sdk="/absolute/path/to/.mozbuild/android-sdk" # Enable artifact building: ac_add_options --enable-artifact-builds # Write build artifacts to: mk_add_options MOZ_OBJDIR=./objdir-frontend
Make sure you edit the path for Android SDK accordingly in the above config.
You should be ready to build with artifact mode!
Important: mach bootstrap currently fails to install rust cross-compile dependencies. See bug 1384231 for updates and a workaround.
Paste the following into your
# 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="/absolute/path/to/.mozbuild/android-sdk" ac_add_options --with-android-ndk="/absolute/path/to/.mozbuild/android-ndk-r18-beta1" # Write build artifacts to: mk_add_options MOZ_OBJDIR=./objdir-droid
Ensure that the Android NDK you've specified (r18-beta1 in the example above) matches what you have installed locally.
Important: mach bootstrap can only automatically download the NDK version currently in use in our automation. However because of a compiler bug in NDK r17b, local ARM builds might not work with that version. As a workaround, please manually download the NDK r18 Beta and extract it to a directory of your choice. If the r18 Beta doesn't work either, try NDK r15c. x86 builds (see below) are unaffected.
If you're planning on hacking the C/C++ code, you probably want to create a debug build instead of a release build. Add the following lines to your
ac_add_options --enable-debug ac_add_options --enable-debug-symbols
I want to build an x86 version of Firefox for Android
Important: Only API versions 15+ are supported on x86 architecture.
Important: Hardware acceleration for Android emulators may not work within virtual machines even if nested virtualization is enabled.
Version 23 and later Android x86 emulators with hardware acceleration are fast enough for local development. They're an attractive alternative if you have recent hardware and an old Android device (or no Android device). Both artifact mode and regular mode support building APKs for x86 architectures. Just replace the line
ac_add_options --target=arm-linux-androideabi with:
API version 15:
API versions 16+:
(You probably want to change the
MOZ_OBJDIR directory, too.) Now when you build, you should produce an x86 version of Firefox for Android!
For more configuration options, see the general Firefox documentation on configuring build options.
Deploy Firefox to an Android device
The bare minimum: run these commands to build, package, install, and run a fresh Firefox for Android on your Android device.
./mach build ./mach package ./mach install ./mach run
mozilla-central subdirectory (created by the
hg clone command).
Building can take a significant amount of time, depending on your hardware, OS, and chosen build options. Linux builds on a fast box may take under 15 minutes, but builds on a slow machine may take several hours. If you're using artifact mode, builds should take less than five minutes. See tips for making builds faster.
Note: The first time you run
mach will ask you if you'd like to create a
.mozbuild directory in your home folder and wait 20 seconds for your answer. This a good default location and you should allow it to create the directory.
To build after making changes, run:
This will only rebuild what is necessary for these changes. It is also possible to use:
./mach build mobile/android
This will build any altered Firefox for Android front-end code. If you are using artifact mode, this should always work. If you are building the Gecko back-end, this may yield incorrect results, so it is not recommended.
Running an Android application on a device is a little more involved than running a Desktop Firefox binary. First, we need to package everything into an Android package. To produce an APK, run:
The produced APK file can be found in your
$OBJDIR/dist folder, and will be called something like
Install and run
To install the Android package to your device and launch it, connect your Android device and enable USB debugging, and then run the following:
./mach install ./mach run
The name of the App that appears on your Android device will be "Fennec $USER", where $USER is the username under which you built the code.
Note: You will need a device running Android Ice Cream Sandwich (API 15) or later.
Additional: GeckoView and GeckoView example
If you want to build GeckoView component, after run
./mach package, run:
./mach android archive-geckoview
The produced APK file can be found in your
$OBJDIR/gradle folder. If you want to install GeckoView example, run:
./mach android install-geckoview_example
Setting yourself up
The compilation step can take some time. While it’s finishing, you should take a moment to sign up for a Bugzilla account!
As well as Bugzilla, much of Mozilla’s internal communication happens over IRC. You can download Limechat here, and learn how to connect to Mozilla with IRC here. If you’re just getting started or have questions about getting set up you can join us in the #introduction channel, where some of our community members hang out to try and help new contributors get started.
There’s one more thing you can do for yourself while you’re waiting: create an account for yourself on Mozillians.
Mozillians is the Mozilla community directory, where you can connect with people who share your interests, projects or countries. This step is optional, but we think it will be worth your while.
Now the fun starts
You’re ready to start hacking. You have the code, you’ve compiled Firefox, and it’s running on your phone. The next steps are up to you: join us on IRC in #introduction and find yourself a bug to work on!
Mozilla's strength is the community behind it; Firefox is the product of a global development team working to keep the Web free, open and participatory, and your contributions will make Firefox and the Web better for hundreds of millions of people around the world.
Developing Firefox for Android in Android Studio
Download Android Studio from developer.android.com. The Firefox for Android front-end team develop the product in Android Studio. There is a Gradle build configuration, parallel to the
mach build configuration. Eventually, we intend to use Gradle in the
mach build configuration.
The Gradle configuration is now "in the source directory". To verify that everything is working, ensure that you've built and packaged successfully, and then run:
./mach gradle clean app:assembleWithGeckoBinariesDebug
Next, simply import the top source directory (
mozilla-central, as produced by
hg clone) into Android Studio. If Android Studio asks you whether you want to update the Gradle Plugin, choose Don't remind me again for this project, as changing to a newer Gradle version on your own may cause problems with your build. You should now have a shiny new Gradle-based project in Android Studio! Try it out by choosing Build > Rebuild project.
It should look something like:
The Gradle build configuration may contain more than one Gradle module, which can define many Run/Debug Configurations. You want the "app" Run Configuration:
See the documentation for more.
Things that are supported in the IDE
- Running, debugging, and profiling Firefox for Android in the IDE. The app project defines the Android Application.
- This includes debugging native code through LLDB - under Run / Edit Configurations… on the Debugger tab, you can switch the Debug type to "Native", add <objdir>/toolkit/library (where <objdir> is the path to your object directory) to the Symbol Directories list, and then start debugging Firefox via Run / Debug 'app' (attaching to an already running Firefox instance might not work).
- Editing Java source code under
mobile/android. Modifications to any of the Java code should prompt a fresh build and install.
- Editing Android resources under
mobile/android, including in
mobile/android/base/resources. In many cases the Android Layout Editor is fully functional.
- Modifying the Android string definitions in
mobile/android/base/locales/en-US/*.dtd. Modifications should be picked up at the next build; they may not be noticed automatically. (This is because the Android
strings.xmlfile is generated, and the generation only happens in response to a build.)
mobile/android, including in
mobile/android/modules, and under
- Editing "omnijar" chrome XHTML, CSS, and JS resources under
mobile/android, including in
mobile/android/content, and under
Things that are not supported in the IDE
- Modifying build system configuration and definitions and modifying
mobile/android/base/AndroidManifest.xml.inor the sub-manifests. See bug 1221344 for an example of what can go wrong here.
- Modifying generated Java code such as
- Modifying C++ source code anywhere in the tree.
mobile/android, say under
dom/, the changes will be recognized the next time "omnijar" files inside
- Running Robocop tests. (Use
mach robocopto run these tests locally.)
mach testto run these tests locally.)
First, check if the Gradle configuration is working:
./mach gradle clean app:assembleWithGeckoBinariesDebug
That should complete successfully.
Second, ensure that you can install the APK to your device:
./gradlew clean app:installWithGeckoBinariesDebug
This should complete successfully.
- It's possible to confuse the IDE about the state of the source directory. To recover, try the following:
- Select the root project and refresh everything in the IDE.
- Open the root
build.gradlefile. If the IDE warns that the Gradle configuration has changed, accept the offer to Sync now.
- Refresh the Gradle model manually: select View > Tool Windows > Gradle and click the blue Sync button in the top left. In Android Studio, there's an icon to do this in the main toolbar -- it's labeled Sync Project with Gradle Files.
- Clear the IDE cache manually: select File > Invalidate caches and then restart the IDE. (This should never be necessary.)
If you get an error about accepting license agreements during the build, like:
You have not accepted the license agreements of the following SDK components: [Android SDK Build-Tools 25.0.3]. Before building your project, you need to accept the license agreements and complete the installation of the missing components using the Android Studio SDK Manager.
You can fix this error and accept the agreements by running
/absolute/path/to/.mozbuild/android-sdk/tools/bin/sdkmanager --licenses. Look in the
--with-android-sdk section of your
mozconfig file to find the correct path.
Required Android SDK and NDK versions
The Fennec build system requires the following versions:
If your build fails because you're missing one of the Android or Google requirements, your first step should be to run
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, or use the GUI through Android Studio's settings.
|Android SDK Platform||Android 9.0 (API 28)|
|SDK Build Tools||27.0.3|
|SDK Platform Tools||current version (27.0.1)|
|Android SDK Tools||current version (26.1.1)|
|Android Support Repository||current version (47 or later)|
|Google Repository||current version (58 or later)|
|Android NDK||r17b (local ARM builds require r18-beta or r15c because of a compiler bug)|
bug 1207680 tracks listing these version requirements in one place in the source code.