Hacking Gaia

Gaia ist die Sammlung von Webapps, die das Front-End des Firefox OS (Codename Boot to Gecko) bilden.

Alles was Sie auf dem Bildschirm von Firefox OS sehen, inklusive dem Homescreen, wurde nur mit Hilfe von freien Web-Technologien erstellt, 


Quellcode besorgen

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

$ git clone https://github.com/username/gaia.git

Gaia starten

Sie können Gaia entweder auf Ihrem Desktop nutzen oder mit einem kompatiblem mobilen Gerät.


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 here. Currently we recommend installing the latest beta build for your platform. There are builds for Linux (32 bit and 64 bit), OS X and Windows.

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

Note: 64 bit Linux builds do not currently work on some distributions, this is bug 812484. If you have problems try a 32-bit build instead.

$ cd b2g
$ ./b2g

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

$ cd /path/to/gaia
$ DEBUG=1 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.

Note: Debug builds are currently broken on B2G Desktop, so until bug 816957 is fixed you need to run "make" without the "DEBUG=1" part, then re-run make every time you make a change to Gaia.


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

$ /path/to/b2g/b2g-bin -profile /path/to/gaia/profile

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

B2G Device


If you have a compatible mobile device you can also run Gaia by flashing it with Firefox OS. Please see documentation here.

There is also documentation here about testing changes on your device.

Unit Tests


See here for information about writing and running unit tests for Gaia.

Filing Bugs


Bugs are filed on Bugzilla under Boot2Gecko > Gaia.

File a new bug under the Gaia component (or one of the sub-components) here.

Contributing Code


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


  • make sure HTML files are declared <!DOCTYPE html> (i.e., HTML5). IE9+ will load them in compatibility mode otherwise.
  • add a "use strict"; statement (exactly that!) to the top of your JS files
  • 2 spaces for indentation - do not use tab.
  • Line break are free (I promise) don't hesitate to use them to separate logical block inside your functions.
  • Files are named like_this.js.
  • Use single quote instead of double quotes.
  • 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 "commit message including bug number"

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.

To request a review of your patch, add an attachment to the bug in Bugzilla 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 listed here.

The reviewer may ask you to make some changes. Once they're is 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 and add "r=reviewername" to the end of the commit message.

Contacting the Team



Linux B2G Desktop support


The homescreen is empty

Currently, under Linux, OOP frame aren't rendered properly. The homescreen isn't actually rendered here...

If you just want to happily hack on pure UI (css and JS) you can safely run with OOP disabled and avoid those issues. Change the line in build/settings.py

 "debug.oop.disabled": False,


 "debug.oop.disabled": True,

To the profile/user.js in your gaia directory.

Port Forwarding


To forward the socket on the phone to the desktop (for desktop development), you first need to get rilproxy to expose it as such, rather than exposing it to Gecko. In the gaia directory:

 $ make forward

This runs the commands:

$ adb shell touch /data/local/rilproxyd
$ adb shell killall rilproxy
$ adb forward tcp:6200 localreserved:rilproxyd

The file located at /data/local/rilproxyd will be deleted once the rilproxy daemon will start again. As a consequence you have to do this manipulation every time your device restarts.

Restarting B2G on a device from the desktop


adb shell killall b2g

B2G Desktop JavaScript Console


You can run B2G Desktop with the JavaScript console by using the -jsconsole flag

$ /path/to/b2g-bin -jsconsole

Launching an app directly


A "--runapp" option has been added to the B2G Desktop command-line to automatically start an application. The system app is loaded and everything happens like normal; this is not like the old trick where we loaded your app instead of the system app.

"--runapp" takes an argument that it normalizes by lower-casing and removing dashes and spaces, and then checks the argument against the similarly normalized app names from app manifests. For example, the name of the e-mail app is currently "E-Mail", but "--runapp email" will run it. Partial matching is not supported right now, but you can enhance b2g/chrome/content/runapp.js if your app name is unwieldy.

If you invoke "--runapp" without an argument (or an empty argument), the command will print out a list of all the apps it knows about as well as a brief usage message.

One important note is that this command disables the lock-screen as part of its magic and does not re-enable it. The assumption is that you won't use this command on a profile where you are testing the lock screen, or will turn it back on manually. Feel free to enhance the command to behave better if this is a problem for you.

In summary:

./b2g -profile /path/to/your/gaia/profile --runapp email

runs the e-mail app.

reset-gaia and install-gaia make targets


The reset-gaia and install-gaia make targets can be used interchangeably. reset-gaia will purge all the existing profiles, database before push Gaia from your working directory (new setting database will also be initialized); install-gaia will just push updates of Gaia.

Blank screen when B2G Desktop starts


When you start b2g using b2g -profile $GAIA/profile a blank screen shows up and you see an error Cannot reach app://system.gaiamobile.org. To fix this there are a couple of things you can check

  • Rebuild the gaia profile using DEBUG=1 make profile in the $GAIA directory
  • Run b2g again
  • If this doesn't fix it, check if there is any other process listening on port 8080. The default profile of gaia starts httpd.js, which listens on port 8080. When running a debug profile, b2g connects to localhost:8080. If some other process is running on port 8080, b2g will fail to display the home screen of gaia
    • To find out if this is the case, you can enable logging on httpd.js. The httpd.js in the profile resides in this location - $GAIA/profile/extensions/httpd/content/httpd.js. Edit the variable var DEBUG=false; to change the DEBUG to true. Save the file and restart b2g. On the console now, you will be able to view the httpd's logs

Diagnosing OOM problems


From Cjones:

Another way to diagnose possible OOMs is to open a terminal and run

$ watch -n 1 'adb shell b2g-procrank'

If you see the "USS" of one of the app processes go up near 100MB and then that process disappear from the process list (accompanied by some sort of visual crash in gaia), then you've almost certainly seen an OOM kill.