github linkedin email
Getting Started with Gaia
May 13, 2014
4 minutes read

Let us dive deep into Gaia. But wait! Before getting started, let us look into the architecture.

Image Source: MDN, licensed under CC-BY-SA 2.5.

Bewildered? Firefox OS is of three-layered architecture. The base being the low level linux kernel (i.e.,) Gonk and above that lies Gecko, a layout engine which reads HTML, CSS, JS, XUL, etc and render it. And at the top level, lies Gaia which is the User-Interface for Firefox OS.

Gaia is written with web technologies like HTML, CSS and Javascript. If you are pretty good with these, you could proceed further, else I would recommend you to get the basics strong before you hack on Gaia.

Hacking with Gaia

Gaia repository is mainained with ‘git’ as VCS. Install git by running

sudo pacman -S git


sudo apt-get install git


sudo yum install git

w.r.t your package manager.

Traverse to your development directory and clone the Gaia repo from git, but wait, we are planning to submit changes to gaia, right? Well, fork it then! And clone the forked repo

git clone

Get some Caffine! Maybe a nap! This would take even an hour as the repo is pretty huge.

Directory Structure

Start with your apps. The directory structure will be like

manifest.webapp file: To store metadata about the app.
style folder: To store CSS files.
js folder: To store JavaScript files.
locales folder:  To store translated strings for different languages.
An HTML file: usually index.html.

Do read the coding style and conventions here.

Setting Up the Device

Let us set-up the system first. Download adt bundle. I would prefer to download SDK tools and then download platform-tools and build-tools, as the ADT bundle consists of too many extra packages as we don’t need ‘em in our case. Extract the bundle to /opt/android-sdk and change the directory rights

chmod -R 755 /opt/android-sdk

Now configure udev rules. Copy the below rule to /etc/udev/rules.d/51-android.rules file

SUBSYSTEM==”usb”, ATTR{idVendor}==”05c6”, MODE=”0666”, GROUP=”plugdev”

You might need to restart your system to refresh the new rules

Get it going! Plug-in your device, turn ON ‘remote debugging’ and ‘screen timeout’ to NEVER.

Don’t forget to set PATH variables to /opt/android-sdk/platform-tools. Need help? Find it here

Test it out.

adb start-server
adb devices

This should show you full_keon (or) keon_device or whatever under “List of Devices attached”

Download b2g nightly build for Keon.

You’ve got the zip file of Keon nightly build of b2g. Unzip it, traverse into the folder and run


Wait until the device restarts. Alright, Into Gaia now!

Make gaia

We’ve got the Gaia repo let us push it into the device. Traverse to Gaia repository and read and files thoroughly. You could also read through

To get started, those relatively easy and mentored bugs are tagged with [GOOD FIRST BUG] Find such bugs here.

If you are comfortable with the bug, please assign it to yourself. Create a local branch

git checkout -b "bugNumber-bugStatement"

As explained in the bug, tweak the code, add a feature (or) fix a bug. To test it out in a device, run

make install-gaia

Check with the code, make changes to the code, and again run

make install-gaia

Now, you can view the changes you made, live on your device!

If you’re working on a specific app and made changes only on it, then to push the changes only for the app, run

APP=calendar B2G_SYSTEM_APPS=1 make install-gaia

Replace ‘calendar’ with the app_name you are working on.

Find more about make options here.

Debugging Gaia with Firefox Desktop

Download Nightly build of Firefox. You’ve got Gaia already. No big deal! Traverse to Gaia repository and run

/path/to/firefoxnightly -profile /path/to/B2G/gaia/profile-debug -no-remote

Done! This will open Firefox. You can see Gaia along with the devtools. Make changes to the code, see it live on a refresh.

Initiating a Pull Request(PR)

When changes are made to the code as per the bug, open your fork on You would get a button Send Pull Request. Click on it and fill up the necessary fields. And Create a Pull Request. Initiate r? to your mentor (In Bugzilla) with the Pull request link. Now, the module peer (or) mentor would make necessary comments on the bug.

When everything goes well, your pull request would be merged to the codebase. Weeh!

The article was drafted assuming you got Linux. If no, you could try installing it with the help of the setps mentioned here.


Back to posts