We're looking for a user researcher to understand the needs of developers and designers. Is this you or someone you know? Check out the post: https://mzl.la/2IGzdXS

Hacking Gaia Redirect 3

This page is targeted at Gaia developers. If you're looking for information about how to build and run Firefox OS, you should consult the Building and installing Firefox OS page instead.

Gaia is the collection of web apps which make up the front end of Firefox OS. Everything you see on the screen in Firefox OS is built using open Web technologies. This includes the home screen and all the default apps. This article provides a detailed guide to modifying Gaia.

Getting the source

To get the source code for Gaia, fork us on GitHub and then clone your fork using git.

$ git clone https://github.com/mozilla-b2g/gaia.git

Running Gaia

You can either run Gaia on the desktop, in Firefox, or on a compatible mobile device.

B2G desktop

B2G desktop is a desktop build of the app runtime used on Firefox OS devices which you can use to run Gaia on your desktop computer.

You can download a nightly build of B2G desktop from the Firefox Nightly site. Depending on what version you are targeting, you may want a specific version of latest-mozilla-b2g18. There are builds for Linux (32 bit and 64 bit), Mac OS X and Windows.

Nightly builds come packaged with a recent version of gaia. Once you've downloaded the archive, all you need to do is extract it to a folder and run the b2g binary from the extracted folder.

$ cd b2g
$ ./b2g

To run B2G with your own version of Gaia for development purposes you first need to build a profile from your clone:

$ cd /path/to/gaia
$ DEBUG=1 DESKTOP=0 make

This will generate a directory in your gaia directory called profile. The DEBUG part runs Gaia as hosted apps on a built-in web server, rather than the default packaged apps which have to be re-packaged after every change. You can find the path to the profile directory by taking a look at last line of output after running the above command, which should look like:

Profile Ready: please run [b2g|firefox] -profile /path/to/gaia/profile

You can then run B2G Desktop with your generated profile like so:

$ ./b2g /path/to/gaia/profile

If you want to you can build your own B2G desktop from source.

Note : On Mac OS X, the b2g binary will be inside B2G.app. You will need to run:

./B2G.app/Contents/MacOS/b2g /path/to/gaia/profile

Using Gaia in Firefox

It's also possible to run Gaia inside of Firefox. This gives you the advantages of having a rapid development cycle, as well as standard web development tools and debuggers. See Quickstart guide to Gaia development in Firefox for details on how to do this.

Using Gaia on a device

If you have a compatible mobile device you can also run Gaia by flashing it with Firefox OS. See Building and installing Firefox OS for details on how to do this. We also have documentation for how to test Firefox OS.

Unit tests

See Gaia unit tests for documentation about how to create and run unit tests for Gaia.

Filing bugs

Bugs are filed on Bugzilla under Firefox OS > Gaia. File a new bug under the Gaia component (or one of the sub-components).

Contributing to Gaia

Mozilla depends on contributions from the open source community to help develop Gaia apps and we'd love you to get involved.

Some great places to find some bugs to start hacking on:

Coding style basics

  • Background:
  • Make sure HTML files are declared <!DOCTYPE html> (that is, as HTML5 documents). If you don't, Internet Explorer 9 and later will load them in compatibility mode.
  • Include the "use strict"; statement (just like that, including the quotes) to the top of your JavaScript files to put them into strict mode.
  • Always use two spaces for indentation, rather than tabs.
  • Please use line breaks to separate logical bits of code!
  • Multi-word file names should use the "underscore" character to separate words, like_this.js.
  • Use single quotes instead of double quotes for strings.

Additional rules


if (expression) doSomething();


if (expression) {

If you're working on the system app, check out the guidance listed here.

Before submitting a patch we recommend you run gjslint on it to check for any style errors:

gjslint --nojsdoc my_file.js

Submitting a patch

First file or assign a bug to yourself on Bugzilla, you'll need a Bugzilla account.

Then create a branch on your fork of Gaia:

$ git branch branchname
$ git checkout branchname

Commit your changes:

$ git add /file/to/add
$ git commit -m "Bug XXXXX - Fix the broken Gaia and save the world"

Push your branch:

$ git push origin branchname

Send a pull request by navigating to the branch in your fork on GitHub and finding the pull request button.

Note: Except under unusual circumstances, patches should be landing first on the master branch, not a release branch like v1-train, v1.3, etc. If they need to land on a release branch, they must go through the usual approval process as outlined on the B2G Landing wiki page.

To request a review of your patch, attach the pull request to the bug in Bugzilla by referencing the URL of the pull request, and set the review ("r") flag to "?" and enter the bugzilla ID of one of the module owners and peers (very important - otherwise your bug will not likely be seen by anyone). The Github tweaks for bugzilla extension on AMO can help automate this process by automatically creating the attachment and adding it to the bug; you will still need to set the review flag on Bugzilla.

The reviewer may ask you to make some changes; you may need to amend the original commit and force push it to the original branch/pull request. Once they're happy with your patch, they will merge it into the master branch for you. Before they do this they would prefer it if you could squash all your changes into a single commit, so your contribution can be tracked easily.

The person who merges the commit (usually the reviewer) would add a r= flag in the comment of the merge commit.

Make options

you use the make command inside the Gaia repo to create a Gaia profile that can be loaded onto your device or run in a B2G Desktop build. This section looks in detail at the different make options available.

There are many environment variables present in the Makefile. Do not depend on them as they may be removed in the future.

Created profiles are stored in /gaia/profile, and contain the following items:

  • defaults: Directory containing default settings to be reloaded after you reset the phone.
  • extensions: Directory containing extensions.
  • settings.json: Settings file.
  • user.js: Another file containing more settings/preferences.
  • webapps: Directory containing all the web apps that are to be installed on the phone.

Note: When you've already made a profile and you want to build a new one, you must delete the existing profile directory before trying to generate a new one.



This simply gives you an unbranded, non-debug build. For a branded build build you need to use Official Mozilla branding make; for a debug build you need Debug make.

Push to device

make install-gaia

make reset-gaia

make profile

With ADB (Android Debug Bridge) setup, these make targets will push Gaia to the device. reset-gaia will purge all existing profiles, web apps and database entries (a new settings database will be initialized) before pushing Gaia from your working directory to your device ; install-gaia will just push updates of Gaia. make profile pushes the existing profile, created with other make options detailed in this article.

Build specific apps

APP=system make

APP=system make install-gaia

When a profile already exists, APP allows you to specify which app to re-package, instead of re-packing and re-pushing all the Gaia apps.

Specify custom profile folder

You can specify a custom directory to build your profile in, using PROFILE_FOLDER, for example:

PROFILE_FOLDER=profile-b2g-desktop make

Different types of build

There are a few make options that create different types of build, with different purposes.

Production make


This creates a production build of Gaia:

  • Gaia is run as packaged apps, which are harder to debug, but are the best available state for apps in terms of available API permissions, etc.
  • Test apps are not included in the build
  • Remote debugging is turned off by default
  • Lock screen is turned on (which in turn will cut USB connections)
  • Marionette is turned off
  • First time user experience is turned on
  • Offline cache is used.

Note: You can also use the alias make production.

Debug make

DEBUG=1 make

The DEBUG variable runs Gaia as hosted apps on a built-in web server on a specific GAIA_PORT, rather than the default of packaged apps which have to be re-packaged after every change; this makes things easier to test. Launching the profile with the latest Firefox Nightly will also give you nice B2G specific panels on the Firefox Developer Tools.

In addition:

  • Test apps are included in the build.
  • Remote debugging is turned on by default.
  • Lock screen is turned off (USB connections won't be interrupted.)
  • Marionette is turned on, which is needed when running Gaia unit tests.
  • First time user experience is turned off.
  • Offline cache is not used, even if it is generated.

Device debug make


This disables screen lock on the device, and enables debugging with the ADB tool, so is useful for device debugging.

In Firefox OS version > 1.2, specify this param when you want to debug Firefox OS webapps with the App Manager.

Debug desktop make


This option creates a desktop debug version, for running inside B2G desktop.

Official Mozilla branding make


Use this to make an official Mozilla-branded build.

Dogfood make

DOGFOOD=1 make

Dogfooding options and utilities are turned on, for example the Feedback app, which allows doog fooders to easily submit feedback on the OS.

System apps make


This environment variable lets you push an app to /system/b2g instead of /data/local. You should use this when you work with a user build. This variable is automatically set when running make production. This can be used for install-gaia or reset-gaia too.

Distribution and market customization build


Note: Read Market Customizations for more details.

Developer/debugging options

There are also make options for adding/removing features or changing settings, for debugging purposes.

Enable remote debugging


This enables remote debugging on the device, the same as using the option in the developer settings.

JavaScript optimization make


This triggers an optimization pass on Gaia's JavaScript, concatenating/compressing the files. This is automatically set when running make production. This can be used for install-gaia or reset-gaia too.

High resolution image assets


When packaging the app, this option replaces images with their *@1.5x.(gif|jpg|png) equivalents if such images exist. You need to use the above option as part of a standard make command, for example:

GAIA_DEV_PIXELS_PER_PX=1.5 make reset-gaia

GAIA_DEV_PIXELS_PER_PX=1.5 make install-gaia

Gaia is currently targetting the following screen resolutions:

  • qHD: ~540×960; device pixel ratio = 1.6875
  • WVGA: ~480×800; device pixel ratio = 1.5
  • HBGA (320x240); device pixel ratio = 1

use GAIA_DEV_PIXELS_PER_PX to make sure the images looks sharp on qHD and WVGA devices. see A pixel is not a pixel for more information about device pixels per css pixels.

Disable first time use experience (FTU)


Disable the FTU with this environment variable.

Disable lockscreen

You can disable the Firefox OS lockscreen using the NO_LOCK_SCREEN option, for example:


Reference Workloads

Reference workloads allow developers/testers to quickly install a large amount of data in several applications, typically on a newly-flashed phone.

The commands are (from the gaia directory):

make reference-workload-light
  • 200 contacts
  • 200 sms messages
  • 50 dialer history entries
  • 20 gallery images
  • 20 songs
  • 5 videos
make reference-workload-medium
  • 500 contacts
  • 500 sms messages
  • 100 dialer history entries
  • 50 gallery images
  • 50 songs
  • 10 videos
make reference-workload-heavy
  • 1000 contacts
  • 1000 sms messages
  • 200 dialer history entries
  • 100 gallery images
  • 100 songs
  • 20 videos
make reference-workload-x-heavy
  • 2000 contacts
  • 2000 sms messages
  • 500 dialer history entries
  • 250 gallery images
  • 250 songs
  • 50 videos

These targets accept the APP environment variable, or an APPS environment variable that should contain the app names separated by a space, e.g.:

APP=sms make reference-workload-light
APPS="sms communications/contacts" make reference-workload-heavy

The apps available are:

APPS="gallery music video communications/contacts sms communications/dialer"

In order to install music (songs) with reference workloads, the utility mid3v2 must be installed. This utility can be installed with:

sudo apt-get install python-mutagen

If you run Fedora or RHEL instead, use:

sudo yum install python-mutagen

Documentation make

Gaia docs can be built, via jsdoc3. To generate these, you can use the following command:

make docs

Enabling IME layout and dictionaries

To enable keyboard IME layout and dictionaries enabled, use following command structure:

GAIA_KEYBOARD_LAYOUTS=en,zh-Hant-Zhuyin,el,de,fr,zh-Hans-Pinyin make

Customizing the build-time apps

The apps that run on Firefox OS are all contained within the Gaia source tree, in one of two locations:

  • gaia/apps: This is where the system default apps are found, such as calendar, email, settings, etc.
  • gaia/external-apps: This is where the Firefox Marketplace app is found (marketplace.firefox.com), and where apps subsequently installed by the user are stored.
  • gaia/showcase-apps: This is a container for multiple showcase apps, for example a 3D Crystal Skull to show off WebGL performance on the device.
  • gaia/test-apps: This directory is a repository for simple tests, designed to test simple B2G features.
  • gaia/external-apps: This directory contains more tests.
  • There may be oters too, depending on the version of Gaia you have cloned.

Note: If you are building B2G rather than Gaia, the paths will of course have B2G/ on the front, e.g. B2G/gaia/apps and B2G/gaia/external-apps.

If you want to omit some of these apps from your build of Gaia/B2G, you can do this in a few different ways:

  1. The "brute force" method is to simply delete the apps you don't want to be present at build time, before building.

  2. The more refined method is to edit the gaia/build/config/apps-*.list files to include the paths to the apps you want to include at build time. For example, gaia/build/config/apps-production.list looks something like this:


    But you could also include specific apps rather than just picking them all, for example:


    The mechanism for choosing which apps-*.list file is used during the build to determine the available apps is contained inside gaia/Makefile:

    ifeq ($(MAKECMDGOALS), demo)
    else ifeq ($(MAKECMDGOALS), dogfood)
    else ifeq ($(MAKECMDGOALS), production)
    ifeq ($(PRODUCTION), 1)
    ifeq ($(DOGFOOD), 1)
    ifndef GAIA_APP_CONFIG

    Initially, the GAIA_APP_TARGET variable is set to engineering, so by default building gaia from source will use app-engineering.list (which includes all the tests, demos, etc.):


    To specify usage of a different apps list you specify different options when running the make command. To build with apps-production.list, for example, you'd use

    PRODUCTION=1 make
    • If you specifically build with DEMO=1 specified, then it will use apps-demo.list.
    • If you specifically build with DOGFOOD=1 specified, then it will use apps-dogfood.list.
    • You can completely override the decision by using GAIA_APP_CONFIG and providing your own apps-*.list file.

    gaia/Android.mk contains these lines:

    ifneq ($(filter user userdebug, $(TARGET_BUILD_VARIANT)),)
    B2G_SYSTEM_APPS := 1

    When you build, if VARIANT=user or VARIANT=userdebug are set (these wind up getting reflected in the TARGET_BUILD_VARIANT variable), PRODUCTION=1 is automatically set when building gaia.

  3. The third, and most refined (but most complex) method is to use customizations. These allow you to specify build-time customization instructions in separate difrectories, without modifying the core Gaia repo. You can include your own customizations in distinct directories, or use the preexisting directories that come with the source.

    For example, the basic Firefox tablet customized app list is defined in apps.list under the distribution_tablet folder (gaia/distribution_tablet). These customizations can be applied at build time using options like this:

    GAIA_DISTRIBUTION_DIR=distribution_tablet make

    Note: Customizations is its own separate topic entirely. To learn more about it, read Market Customizations.

    Note: If you want to include custom external apps as part of your Gaia build, you need to build them in a specific way, and then place them into the gaia/external-apps/ folder. Read Building Prebundled web apps to find out how.

Important: If you are a device vendor creating a custom B2G/Gaia build for distribution, you need to satisfy certain criteria before you are allowed to include the Firefox Marketplace app on your phones/tablets/etc. Contact Mozilla for more details.

Contacting the Team

Document Tags and Contributors

Last updated by: Sheppy,