Using Gaia in Firefox Redirect 2

This guide provides a very quick first step to debugging and developing Gaia apps, including running Gaia inside desktop Firefox and in the Firefox OS App Manager. This guide assumes that you know HTML5 technologies, have knowledge of MVC patterns and have keen interest in Firefox OS. By the end you will have a basic understanding of Gaia app structres, and a basic workflow to modify Gaia apps and test your work.

What do you need?

There are two options for setting up a Gaia/B2G development envinronment. You can set up your own, or you can use the FoxBox virtual build environment. Let's run through both of these options.

Setting up your own environment

  1. First of all you need to have Git installed. If you prefer working in a visual environment, you might also consider installing the Github client (Github for Mac / Github for Windows). Git is essential for updating the code, promoting your changes, and seeing what other developers are working on.
  2. Next, you need to get the Mozilla Gaia repository onto your machine: The best way to do this is to fork it and then clone your fork onto your local computer using git clone<your github name>/gaia.git. This could take a while, as the repo is rather large: about 700MB.
  3. After this is done, you should use a terminal to enter the repository (cd gaia) and then run the DEBUG=1 make command to build and configure Gaia correctly for debugging. This downloads XULRunner — Mozilla's runtime package for installation, updating and uninstalling — and uses it to perform the required build procedure.
    Note: Read more details about Gaia Make options if you want to know more.
  4. After you are done with setting up your workspace, you need to install the Nightly build of Firefox.
  5. In that Nightly build, you could also choose to use the Firefox Simulator Extension and App Manager Extension, depending on your preferred workflow (both are covered below). The App Manager extension should be pre-installed in the nightly build, but you'll need to install the Firefox OS simulator if to use via the App Manager, if you don't have a real device to test on.
  6. You will need to install the ADB helper for debugging on the remote device, AKA your phone.
  7. You might want to get a Firefox OS phone. It will show you various use information related to the start time of apps, frame rates, etc. Also, once you have the actual OS running on a device, you will be able to easily test all the supported device APIs.

Setting up the FoxBox virtual environment

FoxBox is a Firefox OS build environment contained in a VM (Virtual Machine), powered by Vagrant and Virtualbox. This has many advantages, but the main one is that it does a lot of configuration for you, leaving you to get on with development work. For full instructions, read the FoxBox Github repo README.

Now that you have the basic workspace setup, lets get to the apps!

Firefox OS's default apps

The default HTML5 apps provided in the Gaia source code are as follows:

  • Bluetooth
  • Browser
  • Calendar
  • Camera
  • Clock
  • Contacts
  • Cost Control
  • Dialer
  • FL
  • FM
  • Gallery
  • Homescreen
  • Keyboard
  • Music
  • PDF.js
  • Ringtones
  • Search
  • Setringtone
  • Settings
  • SMS
  • System
  • Video
  • Wallpaper
  • WAPPush

The first app that gets launched when the phone starts is the System app. This app is responsible for opening and managing the Homescreen app. From the Homescreen app,  you can launch the other apps to perform various functions.  For example, the Dialer app gets launched from the Homescreen app when a user taps on the phone icon. This Dialer app can then launch the Contacts app when the user wants to see the list of contacts to dial.

Let’s explore some apps

The default apps are all contained in folders inside the gaia/apps/ folder. Each Gaia app folder contains the following components:

  • 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 (but not limited to) index.html.

Some apps may also have:

  • elements folder: To store other views in HTML files.
  • test folder: To run the tests related to the application.
  • resources folder: Contains other resources such as movies, sounds, etc.
  • build folder.

Important: There might also be some additional files like LazyLoaders and Customized Templating Engines and other utilities at work in a Firefox OS app. You may notice different JavaScript patterns in different apps or .js files. Remember, it is an open source app/OS, so it is coded by many different people. Therefore the apps are often created according to different patterns and coding styles!

Note: This is the general layout for Gaia apps. Your own web apps only actually require a manifest.webapp file; everything else is optional.

If you are experienced in web development, you will already have all you need to make some modifications to these apps. Get improving.

Let's fire up some apps

After you have made modifications to those applications, you will want to see the changes in action. You can either run them inside Firefox Nightly, push them to your physical device, or run them through the Firefox OS App Manager (in a simulator or on a real device).

Running in Firefox Nightly

To run Gaia and view the apps in Firefox Nightly, you have to run a command with the following structure:

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

For example, on Mac OS X, we ran the following command:

/Applications/ -profile /Users/bob/git/gaia/profile-debug -no-remote

Note: -no-remote is needed to prevent reusing a running Firefox instance instead of creating a new one running the custom Gaia profile. profile-debug just means we are running the debugging profile of Gaia we built earlier with the DEBUG=1 option on the make command , with the environment set up for debugging.

This takes a while to start up, but eventually you'll end up with a Gaia instance plus several controls running in a new browser window:

A UI screen showing the Gaia user interface running in Firefox nightly: a phone screen and number of tool bar controls.

Alternatively if you just want to run a single app in the browser, a much quicker approach is to simply open the app's root HTML file in the browser via a file:// URL (i.e. by opening index.html in the browser). You can then use the Responsive Design View tool to see what it will look like on small screen resolutions. This is a useful approach if you want to do some rapid UI development/debugging and has the advantage of almost instant reloads. The Firefox developer tools can be really useful here, for example for testing CSS tweaks.

Note: That this approach will not have access to the device hardware so lots of functionality will not work, plus you won't get to see the app start up, see its icon on the home screen etc. Running on a physical device is the best approach overall, see below.

Running on a physical device

To push your modified Gaia to a physical Firefox OS device:

  1. Make sure you have adb installed, or install ADB helper as described above.
  2. Check that your phone is successfully connected to your computer over adb by entering the adb devices command into your terminal.
  3. Enter the command make reset-gaia from inside your Gaia directory to push it to your device over adb.

This can take a while, but there is an easier quicker way — using the App Manager.

Running through the App Manager

As long as your device is running Firefox 1.2+, you can just run the modified app in the App Manager, as covered in the next section.

Debugging with the App Manager

After you are done modifying apps (or creating some of your own), you might want to debug them.

To do so, first of all get the App Manager and your physical device talking to one another, or use the Firefox OS simulator if you don't have a physical device. This is all explained in Using the App Manager.

Now select the app you want to debug — use the Add Packaged App control inside the App Manager and select the directory your app to debug. When the app first comes up you'll need to press its "Start" button to install it on the device/simulator and then start it up. From then on, you can press "Update" to push further updates to the device/simulator, and "Debug" to use Mozilla's developer tools to debug the app directly on the device.

For example, below you can see the Contacts app running in the App Manager.

A card showing details of the Gaia contacts app: a simple contacts application.

Try out some of the debugging features, for example runing some console commands, or modifying some CSS properties.

A screenshot of the Mozilla App Manager

Contributing code back to the project

Once you are satisfied with the changes you've made in the Gaia repo, you can submit pull requests back to the repo on Github. If you are not sure how to do this, read Using Pull Requests on the Github help pages.

In reality, your pull requests are unlikely to be accepted by the Gaia development team without some discussion and agreement. Your first course of action should be to discuss the changes you want to make with the development team. They can be found on the mailing list, or in the #gaia IRC channel on Mozilla IRC.

Another course of action is to file bugs on the Mozilla Bugzilla system, using the Firefox OS project bug form (choose Gaia — or an appropriate subset — as the component.) First of all you should search Bugzilla to see if the issue has already been filed by someone else. If not, consider the following two points:

  • If your bug concerns something that is obviously wrong — a bug in the real sense of the word — then you should justy file it.
  • If your bug is for a feature request, then it is probably best to discuss it on the mailing list/IRC first.

Note: If you are not sure what to work on and just want to find relevant bugs to contribute to, Josh Matthews' Bugs Ahoy app is useful.


The following subsections answer some common questions about debugging apps using Gaia on the desktop.

Note: Refer to Hacking gaia for more make options that can be set that are useful for Gaia debugging.

Can I emulate high resolution devices inside the Firefox desktop browser?


  1. First of all, you can use the command
    to make sure the images look sharp on qHD and WVGA devices.
  2. Next, you can change browser density by opening the about:config page in Firefox and setting the layout.css.devPixelsPerPx flag to 1.5 .
  3. Last, you can use the Responsive Design View to 320 x 533 px (which is the equivalent CSS pixel dimensions to 480 x 800 device pixels.)

Document Tags and Contributors

 Last updated by: Sheppy,