Hacking Gaia for Firefox OS, part 1

So I guess pretty much everyone is aware of this awesome new product being developed at Mozilla that is making a lot of noise in the mobile world. I am of course referring to FirefoxOS (code named Boot2Gecko) and if you have not heard of it yet, then you need to head over to the product page right now and also, the Wiki for a more technical overview.

Not to go into too much detail and restate what is already on the wiki, FirefoxOS is made up of three distinct parts:

  • Gonk – The ‘OS’ i.e. low level Linux kernel and hardware abstraction layer (HAL)
  • Gecko – The application runtime, also present in your desktop and mobile Firefox
  • Gaia – The user facing front end of the OS

Contributing to Gaia

As a front-end engineer this new OS opens a world of new possibilities but, did you know, you can also be part of and contribute to Gaia? This is true, and starting today I will be writing a series of posts on how you can get involved. Today’s topic is how to get a working environment that enables you to work on, test and contribute to Gaia. Ok then, let’s get started.

First thing right out of the door is to head over to Github and fork and clone the Gaia repo.

git clone git://github.com/yourusername/gaia.git && cd gaia

After the above is complete, you are ready to make your local Gaia profile. Inside the gaia directory, which you should be in now, run:

DEBUG=1 make

The process above is going to do a bunch of things and the first time you run it, it is going to take some time so my suggestion is, take a break and make yourself some coffee. Once the above has completed the last line of output should be something like:

Profile Ready: please run [b2g|firefox]
-profile /Users/schalkneethling/mozilla/projects/gaia/profile

Downloading B2G desktop build

Keep a note of the -profile flag as you will need it in a minute. Next we need to download a B2G desktop build. For work on version 1 of Gaia, which is the current focus, we are going to be using the Aurora builds, on the linked FTP page, select the latest build for your platform and once downloaded, follow the usual process for installing an application on your environment.

Note: Due to some changes in the way events are sent and handled by apps the most recent builds of the B2G desktop will not work. To get around this, and ensure a more stable dev environment, you can make use of the builds from http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-b2g18/

Now that we have our profile and desktop build, let’s join the two. Open up a terminal (command line) and enter the following:

/path/to/b2g-bin -profile /path/to/profile

# Note: On Mac the path is slightly different as b2g-bin lives
# inside the Contents folder of the .app so here use:

-profile /path/to/gaia/profile

Set-up app

Once you run the above, a window will open up sized to the dimensions of the current FirefoxOS target device device and the set-up app will be will be visible. Click through this and complete as needed. After this, there will be a phone tour app loaded which you can either follow or skip.

Screen shot of a running B2G Desktop

NOTE: Currently there is a bug in the desktop build and once you exit the tour, you will be presented with a black screen. To get to the lock screen you will need to close down B2G (Ctrl+C should do it) and relaunch. If you build your Gaia profile with DEBUG=1 and are getting 404s when B2G loads, you might find that you need some entries in your etc/hosts file (some need it, some don’t). Here is a gist that you can simply copy into it (A nice tool to manage you hosts file on Mac is GasMask)

Making changes to the code

Once you have clicked around the interface a little, let’s look at making a simple change to one of the current apps and see our change reflected.

With B2G running, open up the Calendar app, it should be located on the third screen to the right of Home, on the top left. At the bottom you will see the usual triggers for displaying the calendar by month, week or day. Now in your editor of choice open up the index.html file inside gaia > apps > calendar

Screen shot of FirefoxOS showing calendar app icon

At around line 180 you will see the HTML that reflects the tabs I just referred to. Go ahead and completely remove the <menu> element and save the file.

<menu id="view-selector">
  <li class="today">
    <a href="#today">Today</a>
  <li class="time-selection">

Next, without rebuilding Gaia, simply close B2G and relaunch. Now open up the calendar app again and this time you will see that the tabs from before are gone as expected. Great! Now go back and undo your changes and relaunch B2G and the calendar app again. Your tabs should now be back and working as before. This shows a simple example of a common workflow when developing with B2G desktop.


One of the things that is tricky within this environment is debugging but, we are not left with nothing. If you start-up B2G as before but append the -jsconsole flag, you will now see that the error console you know from Firefox, open up alongside it. This is useful when you want to check for script errors or log messages out to the console.

Screen shot of B2G desktop running with jsconsole

Just to see how this will work, open up the month.js file inside gaia > apps > calendar > js > views and after the first line add:

console.log("Test log message when loading the Calendar App....");

Save the change and launch B2G with the -jsconsole flag. Once launched, click on the messages tab of the error console and then go ahead and open up the calendar app, you should now see your message printed.

NOTE: If you do not see your messages being logged to the console it might because console logging has been disabled. To remedy this, head to the Settings app on FirefoxOS, then Device Information > More Information > Developer > Console Enabled.

This then concludes the first post in this series but before ending the post, here are some useful places to get info and speed up development:


  1. MrEricSir

    Psst, HTML special characters don’t belong on the command line!

    January 14th, 2013 at 11:41

    1. Robert Nyman

      Thanks, it was a little encoding problem. Fixed now!

      January 15th, 2013 at 02:11

  2. Bob Pelerson

    I still don’t understand why Firefox OS chose the Linux kernel over FreeBSD? It seems like a wacky and clueless decision.

    January 14th, 2013 at 14:04

    1. Schalk Neethling

      Hey Bob, thanks for the comment. I believe the biggest reason for having chosen the Linux kernel is because we could gain a lot of ground quickly by using the Android kernel for our Gonk layer and as such, Linux came as part of the package.

      I am curious though, why would you have chosen FreeBSD over a Linux kernel?

      January 15th, 2013 at 00:59

  3. Fawad Hassan

    Thanks for this post. I needed it badly!
    It would be more helpful if you explain high level architecture or give some overview of Gaia in upcoming parts so new comers like me can find good starting point to deep dive in Gaia code.

    January 14th, 2013 at 22:42

    1. Schalk Neethling

      Thank you for your comment Fawad. There is definitely more to come in the coming weeks including more development tips as well as a look at the Gaia source and architecture. Stay tuned ;)

      January 15th, 2013 at 00:57

      1. markg

        Here is an MDN reference on Firefox OS architecture:

        March 13th, 2013 at 17:22

  4. Thomas

    Unfortunately all I can get is a black screen when trying to launch B2G with my profile (gaia is up-to-date on the master branch). I’m using the following command:

    λ ~/Code/gaia/ master /Applications/B2G.app/Contents/MacOS/b2g-bin -profile /Users/tbassetto/Code/gaia/profile
    1358263010274 Marionette INFO MarionetteComponent loaded
    1358263010275 Marionette INFO marionette enabled, loadearly: false
    ###################################### forms.js loaded
    [AccessFu] INFO attach

    B2G.app comes from http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-b2g18/b2g-18.0.multi.mac64.dmg

    January 15th, 2013 at 08:23

    1. Fawad Hassan

      If you are able to view the tour and then the black screen appears, then maybe it’s this problem:

      “NOTE: Currently there is a bug in the desktop build and once you exit the tour, you will be presented with a black screen. To get to the lock screen you will need to close down B2G (Ctrl+C should do it) and relaunch.”

      January 15th, 2013 at 09:06

      1. Thomas Bassetto

        Nope, it was a black screen from the start, before a hypothetical tour.

        I modified my /etc/hosts and it was still not working. But I did another `DEBUG=1 make` and now it works! ;)

        January 15th, 2013 at 10:37

  5. Fawad Hassan

    b2g Desktop shows white page and give error “404 page not found”.

    I successfully build the gaia and downloaded the stable Linux x86_64 version of b2g. When I ran b2g using this command:

    ./b2g-bin -profile /home/ifadey/Projects/gaia/profile

    It shows following output on the terminal and show white page (404 page not found) in B2G Desktop window.

    1358259547941 Marionette INFO MarionetteComponent loaded 1358259547943 Marionette INFO marionette enabled, loadearly: false ATTENTION: default value of option force_s3tc_enable overridden by environment. ###################################### forms.js loaded [AccessFu] INFO attach creating 1! *** UTM:SVC TimerManager:notify - notified @mozilla.org/addons/integration;1 *** UTM:SVC TimerManager:notify - notified @mozilla.org/extensions/blocklist;1

    January 15th, 2013 at 09:26

    1. Schalk Neethling

      Hey there Fawad and Thomas, there are some entries you can add to your hosts file that should resolve the problem. Instead of posting it here I will update the post to reflect this.

      January 15th, 2013 at 09:45

      1. Fawad Hassan

        It worked but after I restarted my machine.
        Thanks for fix :)

        January 16th, 2013 at 06:29

  6. Lucas Holmquist

    Might be a silly question, but how do you exit an app, once your in it?

    January 15th, 2013 at 09:53

    1. Schalk Neethling

      Hey there Lucas, not a silly question at all. On OSX there are the hardware button simulations: https://wiki.mozilla.org/Gaia/Hacking#Simulating_Hardware_Buttons

      January 15th, 2013 at 11:40

    2. Schalk Neethling

      Hey there Lucas, the post has been updated, please see the last bullet point at the end of the post. Thanks for your comment.

      January 15th, 2013 at 13:13

  7. merih

    Hi, I could not manage to make it work. After running ‘b2g-bin’ with the profile under gaia folder, a window with tomcat’s “It works!” page is opened only. However, if I run ‘b2g’ (directly or with profile) it seems to be working.

    January 16th, 2013 at 07:25

    1. Merih Akar

      OK I’ve solved my problem. The problem was, httpd.js is listening on port 8080, however I have also tomcat installed in my machine which also listens on 8080. I have stopped tomcat and it started to work.

      January 16th, 2013 at 09:37

    2. Schalk Neethling

      Hey merih, from what you state it would seem that you actually have an instance of Tomcat running already on the same port as the server Gaia would try to start up when you build the profile using DEBUG=1.

      The reason it works if you run B2G directly is because the bundled Gaia profile is not built using DEBUG=1 and thus the conflict does not occur. You have two options, either stop your Tomcat instance or, build your Gaia profile as follows:

      DEBUG=1 GAIA_PORT=:9090 make

      Now for a bit of bad news though ;( Currently it would appear that specifying a custom port as above does not play nice with B2G desktop so, for right now, best solution is to stop whatever runs on port 8080. Here is the bug regarding this https://bugzilla.mozilla.org/show_bug.cgi?id=831347

      January 16th, 2013 at 12:21

      1. Merih Akar

        I’ve figured it out before your response and stopped Tomcat and voila it works! Anyway thanks for detailed explanation :)

        January 16th, 2013 at 12:44

        1. Schalk Neethling

          Great stuff Merih, glad you got it going, have fun!

          January 17th, 2013 at 04:40

  8. Variya Soft Solutions

    As stated in the article, I know that

    git clone git://github.com/yourusername/gaia.git && cd gaia
    DEBUG=1 make

    are commands to build Gaia repository. But I am not sure where to run these commands or how to use them. Please suggest. Thanks.

    January 16th, 2013 at 09:25

    1. Merih Akar

      you should write them to your terminal

      January 16th, 2013 at 09:38

    2. Schalk Neethling

      Hey Variya SS, I guess the short answer is that you need to run these commands via the terminal/command line. Have you worked with Git before at all?

      January 16th, 2013 at 12:25

      1. Variya Soft Solutions

        No. Never.
        Thank you Merih Akar, Schalk Neethling for this help. Let me try it on my Ubuntu terminal.

        January 16th, 2013 at 22:00

        1. Schalk Neethling

          Hey Variya SS, if you need some help to get going with Git, this is a great starting point https://help.github.com/categories/54/articles

          January 17th, 2013 at 04:40

  9. Thierry Régagnon

    It went well until I deleted the menu in the Calendar App. I stopped B2G and launch it again, but this time I got an error: “Firefox can’t etablish a connection to server at system.gaiamobile.org:8080”. I didn’t had this error at first launch.

    I followed your advice about the hosts file. I used “Gas Mask” to add Gaia rules to my hosts file. I used your gist, but it didn’t work. Then I realized that the port in your Gist is 8180 and B2G try to reach 8080, so I changed all the rules to match the port 8080. It still don’t work.

    Any idea ?

    January 19th, 2013 at 04:01

    1. Schalk Neethling

      Hey there Theirry,

      First thing I would like you to do is head into your checkout of Gaia and completely wack your current profile: rm -rf profile

      Next go ahead and build you profile again without DEBUG i.e. just run make

      Boot up B2G and see whether this works, if this does, proceed to the next step.

      Go back and build your profile again, this time using DEBUG i.e. DEBUG=1 make. Launch B2G and see whether it still works.

      If things fail at any of these steps, please let me know. Also, just to be sure, are you using a build of B2G downloaded from http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-b2g18/

      January 20th, 2013 at 11:40

      1. Thierry Régagnon

        Thanks for your help Schalk.

        I followed your advice and it successfully worked.

        I tried different things to understand the problem. When I stop B2G from the CLI with CTRL + C, and launched it again, I get the error about the inaccessible system.gaiamobile.org:8080.
        When I use the “Power Off” option in Gaia. I have no problem to run B2G again. (but I get the Crash Reporter)

        I tried to remove the menu in the Calendar App. But the App won’t launch after the modification. I get a blank page. I managed to alter the App by another way.

        I couldn’t log a message from the month.js file, even with the Console Enabled option in the Developer menu.

        January 20th, 2013 at 15:09

        1. Schalk Neethling

          Hey Theirry,

          Glad you hear you are making progress. Regarding the issue you are having stopping and starting B2G, I cannot replicate this myself but, on which platform are you, perhaps this is a bug that we can then file.

          Regarding the problem after altering the Calendar app code, did you remove the entire bit of code wrapped by the menu element? If the resulting code is not well formed the rendering of the app will break and you will find that you end up with a white screen. In the end this is not such a big problem as long as you found another way to see a change you made visualized in the app.

          Then with regards to the logs not being visible, did you start up B2G using the -jsconsole flag and build your Gaia profile using DEBUG=1 make? Also, did you click around the different tabs of the console, for example switching to the ‘All’ tab and see whether the message appears there? With that said, console.log messages should appear inside the ‘Messages’ tab in general.

          Please let me know if the above assists you or whether you are still running into problems. Thank you for your comments.

          January 20th, 2013 at 23:51

  10. Patrik Schulze

    You write in the article:

    First thing right out of the door is to head over to Github and fork and clone the Gaia repo.git clone git://github.com/yourusername/gaia.git && cd gaia

    however you dont state where one can find the actual gaia repo, which is confusing

    that would be https://github.com/mozilla-b2g/gaia.git I think

    Anyway, what I need to do is: I have already build, flashed, changed gaia on a mobile device and so on.
    However I really want to change integral parts of gaia, the way it works and looks. It works great on mobile – the problem is after every little change I have to build and flash which takes over 10 minutes.
    So I would like to have a desktop version, so that when I change some css/js/html file, I can see the effect immediately
    Is this possible by building your own desktop build ?
    Because of course the firefox addon and the builds you can download, do not let you do this – you can test apps but not change gaia itself

    March 22nd, 2013 at 04:46

    1. Robert Nyman [Editor]

      Thanks about the link – added that to the post.
      Unfortunately, the way it is right now is to test on the desktop as described above in this article.

      March 22nd, 2013 at 05:29

  11. Patrik Schulze

    The whole Gaia CSP violations stuff is killing me.

    Im trying to write lockscreen widgets and I cant use javascript and select divs – because inling scripts is completely disabled

    March 28th, 2013 at 09:48

    1. markg

      You can still import an external JavaScript file. Have you tried it that way?

      March 28th, 2013 at 11:19

Comments are closed for this article.