Building Firefox OS


 you've set up your build system and performed your initial pull and configure of the code, you can build Boot to Gecko. This guide explains how.

Updating your code

If this isn't your very first time building B2G, you might want to pull the latest code before you start to build. To do that, you should update both the B2G tools and the dependencies, using the following two commands:

git pull
./repo sync -d

You can update a specific make target's repository by specifying its name:

./repo sync gaia

The repo command has other options available that might be interesting; repo help will give you a lot of information.


Note: Before building, you may want to set up a .userconfig file to customize the build. See Customization with the .userconfig file for details.

To build Boot to Gecko, simply use the tool:

cd B2G

Time for another coffee break, or possibly a nap (especially if this is your first build). As in the configure step on the previous page, if you are using a directory of previously-extracted Android system files, you should set ANDROIDFS_DIR before running

Building specific modules

If you want to build just a particular module, such as Gecko, you can specify it by name:

./ gecko

In order to refresh only one application, you can build only gaia module by using the BUILD_APP_NAME environment variable:

BUILD_APP_NAME=calendar ./ gaia

To get a list of the modules you can build, you can do:

./ modules

Setting the number of processor cores to use

By default, the B2G build scripts use the number of cores your system has plus two as the number of parallel tasks to run. You can change this by specifying the -j parameter when running This can be handy if you're using your system for other things while building in the background and need to reduce CPU load a bit. It's also handy when you're having build problems, as it can make reading error output from the build process easier if you have just one task going at a time!

For example, to build using just two parallel tasks:

./ -j2

The most common use case for this, however, is to prevent builds from running in parallel at all. This makes the output of the process much easier to read, making it easier to sort out build problems. To do this:

./ -j1

Building multilocale

To create a multilocale build, do the following:


  1. Determine which Gaia languages file to use. We're currently using locales/languages_dev.json and locales/languages_all.json as our Gaia languages files.
  2. Clone the appropriate locales from into a directory; we use gaia-l10n/. You could use the locales/ directory . You'll need to clone a repo for each locale listed in the languages file.
  3. In your environment, set LOCALE_BASEDIR to the absolute path of the directory in step 2. Set LOCALES_FILE to the absolute path of the file in step 1.
  4. Also, you can set a GAIA_DEFAULT_LOCALE if you want to set a default locale.
cd gaia/locales/
hg clone
Set your environment variables:
export LOCALE_BASEDIR=$PWD/locales
export LOCALES_FILE=$PWD/locales/languages_dev.json

And the languages-dev.json could be replaced by your own languages-own.json path, which could formed like this. You would need to add an entry per each repo cloned in your locales directory.:

  "en-US"     : "English (US)",
  "es"        : "Español"

Since bug 884752 landed (November 2013), to add keyboard layouts (if available in Gaia), you can use parameter GAIA_KEYBOARD_LAYOUTS. 



For example, to add Spanish and Italian keyboard layout, run the previous command adding


At this point you're ready to flash Gaia to the phone for the first time. Connect the phone and make sure Remote Debugging is checked in Settings > Device Information > More Information > Developer.  You only need to do this once, for your own build of Gaia will have that pref turned on thanks to REMOTE_DEBUGGER=1:

 make clean && make production LOCALES_FILE=locales/languages-own.json


  1. Determine which Gecko languages file to use. We're currently using b2g/locales/all-locales as our Gecko languages file.
  2. Clone the appropriate locales into a directory; this can be gecko-l10n/ .
  3. Clone compare-locales.
  4. In your environment, set L10NBASEDIR to the absolute path of the directory in step 2. Set MOZ_CHROME_MULTILOCALE to a string of space-delimited locales from step 1.

    Add the compare-locales/scripts dir to your PATH, and compare-locales/lib to your PYTHONPATH.

    For instance,
    export L10NBASEDIR=$PWD/gecko-l10n
    export MOZ_CHROME_MULTILOCALE="ja zh-TW"
    export PATH="$PATH:$PWD/compare-locales/scripts"
    export PYTHONPATH="$PWD/compare-locales/lib"

    Once you have the above set up, you can run

    You can use .userconfig as well:

    ## Gaia
    export LOCALE_BASEDIR=/b2g/gaia-l10n-transifex-v1.2/
    export LOCALES_FILE=/b2g/languages_propio.json
    ## Gecko
    export L10NBASEDIR='/b2g/gecko-l10n-v1.2'
    export MOZ_CHROME_MULTILOCALE="es-ES eu ca gl pt-BR"
    export PATH="$PATH:/b2g/compare-locales/scripts"
    export PYTHONPATH="/b2g/compare-locales/lib"

There are some mappings between Gaia languages and Gecko ones. For example, in Gaia, Spanish is "es", but on Gecko is tranlated to "Spanish of Spain" (es-ES)

These instructions may change as we smooth things out.

Known errors

"Build failed!"

If you get a general "Build failed" message, you should always try reconnecting your phone to your computer; sometimes the phone can become unmounted for a variety of reasons.

Note that configuring and building B2G for Keon DOESN'T WORK on Mac. You'll need to use Linux to build for this device.

Mountain Lion-specific build errors

1. If you are building on OS X 10.8 "Mountain Lion" (Xcode 4.4.1 or later) and encounter the following error:

external/qemu/android/skin/trackball.c:130:25: error: 'M_PI' undeclared (first use in this function)
Edit the file: B2G/external/qemu/ and add in line 78:
MY_CFLAGS += -DM_PI=3.14159265358979323846264338327950288   #/* B2G_fix: not finding M_PI constant */
2. If you are on Mountain Lion and you receive an error during ./ like:
/System/Library/Frameworks/IOKit.framework/Headers/usb/USB.h:797:9: error: too many #pragma options align=reset

Replace all instances of '#pragma options align=reset' with '#pragma pack()' inside /System/Library/Frameworks/IOKit.framework/Headers/usb/USB.h

Undefined symbols "_sqlite3_androidopt_handle_pragma" and "_sqlite3_androidopt_open"

This error appears if you are building on OS X 10.7 or newer with Xcode 4.5 or newer. To fix this, apply the patch at!msg/android-building/yAfPyUqCsiQ/7zvICk4GWjYJ to the external/sqlite/dist/ file.

KeyedVector.h:193:31: error: indexOfKey was not declared in this scope

This error appears when your gcc version is too recent. Install gcc/g++/g++-multilib 4.6.x versions. See Customizing with the .userconfig file for more information.

Community Note: It is possible to use gcc 4.7.x with slight modifications to the B2G code (gcc will guide you) but you won't get any help! Neither with modifying the code nor with bugs you encounter.

arm-linux-androideabi-g++: Internal error: Killed (program cc1plus)

If you see this message, it most likely means that free memory is lacking. Ensure there is enough free memory before running ./ It should run fine if your system has 4GB of RAM.

" referenced by DSO" error

While building the emulator, if you get /usr/bin/ld: out/host/linux-x86/obj/EXECUTABLES/triangleCM_intermediates/triangleCM: hidden symbol `_XGetRequest' in out/host/linux-x86/obj/STATIC_LIBRARIES/libSDL_intermediates/libSDL.a(SDL_x11dyn.o) is referenced by DSO.

You can get this with some versions in binutils. If you run Debian Stable, you can use the gold linker by installing the package binutils-gold. Note that the gold linker is already installed by binutils, but it's not used by default; binutils-gold does just that.

If you get build errors while the build system is running tests

Sometimes (especially after build tool or operating system updates) you'll get weird errors like this when the build system runs its post-build tests:

Generating permissions.sqlite...
test -d profile || mkdir -p profile
run-js-command  permissions
WARNING: permission unknown:offline-app
WARNING: permission unknown:indexedDB-unlimited
build/permissions.js:122: NS_ERROR_UNEXPECTED: Component returned failure code: 0x8000ffff (NS_ERROR_UNEXPECTED) [nsIPermissionManager.add]
make[1]: *** [permissions] Error 3
make: *** [gaia/profile.tar.gz] Error 2

In this situation, try deleting the gaia/xulrunner-sdk directory and re-pulling the code:

rm -r gaia/xulrunner-sdk

This deletes the downloaded, precompiled copy of XULRunner that the build system retrieves automatically; on your next build, a new copy of XULRunner will be automatically retrieved.

Cannot fetch platform/libcore

If you tried to configure your B2G build for Nexus S (./ nexus-s) and got an error related to libcore, it is because of a problem with the linaro git that feeds into this. To fix this, checkout the B2G manifest like so:

git clone

Edit the nexus-s.xml file in this repo, replacing the linaro git entry with a reference to the aosp entry, which should read like so:

<default revision="refs/tags/android-4.0.4_r1.2"
              sync-j="4" />

Commit these changes (git commit -a) and then change the file in the master branch of the main B2G repo that you checked out to point to your modified local manifest instead of the Mozilla one:


clang errors when building with Xcode 5 on Mac

If you are building on Mac OS X 10.8 with Xcode 5, you will likely see errors like the following:

clang: error: argument unused during compilation: '-include system/core/include/arch/darwin-x86/AndroidConfig.h'
clang: error: argument unused during compilation: '-U DEBUG'
clang: error: argument unused during compilation: '-U DEBUG'
clang: error: argument unused during compilation: '-MF out/host/darwin-x86/obj/EXECUTABLES/obbtool_intermediates/Main.d'
make: *** [out/host/darwin-x86/obj/EXECUTABLES/obbtool_intermediates/Main.o] Error 1

This is because Xcode 5 changes the g++ compiler in /usr/bin, which breaks the build process if you try to use it to compile. In order to work around the problem, edit the following line in build/core/combo/

HOST_CXX := g++


HOST_CXX := g++-4.6
ifeq (,$(wildcard /usr/local/bin/g++-4.6))
 HOST_CXX := g++

Next, you'll want to uninstall gcc, using brew (this assumes you've run the Mac OS bootstrap script — if not, you'll need to complete that step before continuing):

brew uninstall gcc-4.6

Now reinstall gcc with multilib and c++ support:

brew install --enable-cxx

Make sure /usr/local/bin is on your PATH. You can do this temporarily by typing the following into the command prompt:

export PATH=/usr/local/bin:$PATH

You can make the above change permanent by adding it to the .bash_profile file in your home directory.

After you've set your PATH, make sure you can run both of the following commands:

gcc-4.6 -v

g++-4.6 -v

If either of these commands fail, you may need to relink your gcc using brew with the following command:

brew link --overwrite gcc-4.6

It's also possible that /usr/bin/c++ is not pointing at clang++ as it should be with Xcode 5 installed. You can determine if it is by typing the following:

ls -l /usr/bin/c++

It should return something that looks like this:

lrwxr-xr-x 1 root admin 7 Sep 19 11:40 /usr/bin/c++ -> clang++

If c++ is pointing at something other than clang++, update it with the following commands:

sudo rm /usr/bin/c++

sudo ln -s /usr/bin/clang++ /usr/bin/c++

Next steps

After building, your next step depends on whether you built Boot to Gecko for the emulator or for a real mobile device; see the following articles for details:

Submitting bugs on B2G/Firefox OS/Gaia

Once you've got a B2G/Firefox OS build running, you'll probably want to start to file bugs against this specific version, so the Firefox OS community can improve things as effectively as possible. You'll want to file the bug on Bugzilla, under the "Firefox OS" project, but you should include version specifics:

  1. To start with, tell us the major version number, e.g. This can be found on the device under Settings > Device Information.
  2. You can provide more specific version identifiers by  returning the current hashes from the gaia and gecko repositories. This can be done like so:
    (cd gaia;  echo "gaia  $(git rev-parse HEAD)")
    (cd gecko; echo "gecko $(git rev-parse HEAD)")