You can run Gaia in a simulator via WebIDE, in Firefox Mulet (a special version of desktop Firefox for Gaia development), in an emulator, or on a compatible mobile device. This article provides a summary of how to do each, with links to further information.

Note: Sometimes you will come up against a problem related to some of your changes requiring updated perference settings, etc. If you come up against a problem that might be related, try regenerating your profile (run the make command again) to see if it fixes it.

How close is it to the real thing?

Some of the solutions for running Gaia detailed in this article are closer to the experience on a real device than others. The order of ease for running is as follows:

Gaia in Simulator via WebIDE

Gaia in Firefox Mulet

Gaia in Emulator

Gaia flashed on phone

Gaia+Gecko flashed on phone

The order of “how close it is to the shipped product” is exactly the opposite of this. Depending on the feature you’re working on, you’ll have to find the environment that suits the problem.

Explaining the make options

In the below sections on WebIDE and Mulet, you are told to build your own Gaia profile using the following command:

DEBUG=1 DESKTOP=0 make

The DEBUG=1 part creates a debug build, which 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. So to see changes you can just reload the app, which is much more efficient for debugging.

The DESKTOP=0 part has to be included because the default DESKTOP=1 options that comes along with DEBUG=1 is broken and needs to be removed. You won't need to do this in future.

This will build your profile in a directory called profile-debug.

If you want to test with a production build of Gaia for a more realistic test, just run make to build your profile. This will create your profile in a directory called profile.

Using Gaia in Simulator via WebIDE

The quickest way to try Gaia is via WebIDE, a developer tool available in Firefox for Desktop. It provides a number of useful tools to help you test, deploy and debug HTML5 web apps on Firefox OS phones and the Firefox OS Simulator, directly from your browser.

In desktop Firefox Browser 34+, open WebIDE using Tools > Web Developer > WebIDE. Open the Runtime menu on the top right to install and start a Simulator.

To run your own custom Gaia profile, the process is a bit more complex, but still pretty simple:

Before trying to run this, you should build yourself a Gaia device debug profile — go into your Gaia repo clone, and run DEBUG=1 DESKTOP=0 make. This will generate a directory in your gaia directory called profile-debug, containing your profile. With this type of profile you will be able to debug the internal Gaia apps out of the box in WebIDE, plus you don't have to accept the remote debugging confirmation dialog in the simulator each time you start it up. If you want to test using a more realistic production build, just build with the command make.

Install a Firefox OS Simulator by going to Select Runtime > Install Simulator in WebIDE and choosing an option. Make sure you use the same simulator version as the Gaia version you are running (so for example, if your Gaia branch is 2.1, you need to use Firefox OS Simulator 2.1.)

In the right hand menu, you should see your simulator listed. Press the options (gear) button next to it, to access the Simulator Options screen.

Open this simulator in WebIDE, and it should now open with your Gaia profile running.

Note: If the command doesn't work (you might get a message saying "A copy of B2G is already open. Only one copy of B2G can be open at a time." — when it isn't already open) then check your profile directory has read/write permissions set, for example via chmod.

Note: If you want to reset your simulator so it is no longer running a custom Gaia profile, you'll need to go to Firefox about:config, find the extensions.fxos_2_2_simulator@mozilla.org.gaiaProfile pref (2_2 might be different depending on what simulator version you customized), double-click it, delete the value in the resulting dialog box, and press OK.

Using Gaia in Firefox Mulet

It's also possible to run Gaia inside of a special build of Firefox called Firefox Mulet. This gives you the advantages of having a rapid development cycle, as well as standard web development tools and debuggers available to work with.

First of all, you need to need to have the Gaia repo cloned on your machine (see Running your own Gaia build for the best way to do this if you want to contribute to the project.) Mulet only works on Gaia 2.2 and above, so it is a good idea to use the master branch.

Next, cd into the Gaia repo and build your own profile (see make options reference for the different available types) with DEBUG=1 DESKTOP=0 make. If you want to test using a more realistic production build, just build with the command make.

You can now install the latest mulet into gaia/firefox using the command make mulet. This is the quickest way to install it.

If you want more control over where you install mulet, you need to download it yourself — find Windows and Mac builds at Mozilla Central, and look here for Linux. The Mulet builds are the packages whose names start with firefox-*, for example firefox-36.0a1.en-US.mac64.dmg. The Linux builds are called target.linux-x86_64.tar.bz2 — choose the appropriate build for your development machine.

Once downloaded, install the Mulet build somewhere safe so that it doesn't overwrite your normal Firefox Nightly build. For example, on Mac OS X, create a new folder inside Applications called "mulet", and drag it into there.

Now run the Mulet build from the command line, passing it your Gaia profile as the profile to use when opening (signified by the -profile option.) For example, you could run something like this from inside your Applications folder on Mac OS X if you have it installed in there:

Note: If the command doesn't work (you might get a message saying "A copy of Firefox is already open. Only one copy of Firefox can be open at a time." — when it isn't already open) then check you have permission to run the firefox executable like this — you could run the above command with sudo in front of it, although better, more secure practice would be to chmod your install folder.

Note: Newer Gaia versions sometimes require a newer mulet version; to update to the latest mulet, you can run the command rm -rf firefox && make mulet in the gaia/ directory.

On this display you've got the standard Firefox Toolbox available for debugging your Gaia apps, plus an emulation of Firefox OS running on the left hand side, and a number of other tools useful to the Gaia context. The controls above the emulator allow you to:

Turn touch event simulation on and off (if turned off, you can't use the mouse to drag the UI and open apps.)

Take screenshots.

Flashing Gaia on a real device

Important: If you are attempting to Flash Gaia onto a low-memory device such as a Tarako or Spice Fire One, you should Flash it with a special low-memory optimized branch of Gaia, such as the 1.3t branch. Trying to Flash Gaia's master branch onto a low-memory device will probably result in the phone becoming unresponsive.

To Flash a new version of Gaia onto a real device:

First make sure you have the Gaia repo cloned onto your computer, and ADB installed.

If there’s a device attached, you can process the following commands. Or you (Windows or Linux distributions user) may need to check OEM USB Drivers page to correctly setup the USB driver on your computer.

Run adb as root user for real devices using the following command:

$ adb root

Run the following command inside the Gaia repo to reset your phone and update your Gaia source code:

$ make reset-gaia

To test non-system apps, you could install them without rebooting the device with the following command:

$ make install-gaia

If you want to install a specific app only, you can pass it through the APP variable, as follows:

$ make install-gaia APP=browser

Note: Pushing Gaia to your device using make install-gaia / make reset-gaia builds Gaia with 1x resolution assets by default. To specify higher resolution assets you need to use the GAIA_DEV_PIXELS_PER_PX or GAIA_DPPX make options (see High resolution image assets for more details of these options.) When pushing Gaia to your device in this fashion, you should specify the relevant make option along with your device's scale factor, so for example make install-gaia GAIA_DEV_PIXELS_PER_PX=1.5 for a Flame device (or 2, or 2.5, etc; see the scale factor values in the table inside 512 icon for device display.)