Different ways to run Gaia

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: For running Gaia on the desktop, the current recomended way is to use Mulet (see Using Gaia in Firefox Mulet, below.)

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.

Note: There are a lot more make options available for Gaia — see the Gaia make options reference for much more detail.

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.
Open Firefox (Nightly is recommended.)
Open WebIDE using Tools > Web Developer > WebIDE.
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.
Choose Profile > Custom Gaia Profile..., then select your Gaia profile folder in the file chooser dialog.
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 [email protected] 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.
1. 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.
2. 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:
```
./firefox/Contents/MacOS/firefox-bin -no-remote -profile /Users/my-home-folder/git/gaia/profile-debug/
```

The resulting Mulet build should open up, like so:

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:

Choose different screen sizes for the emulator (this is basically Responsive Design View).
Rotate the emulator screen.
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.
Make sure you have Debugging via USB enabled.
Connect your device to your computer via USB.
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.)

To check if your device is correctly connected via USB, you can type:

$ adb devices

You should get a result like so:

List of devices attached
emulator-5554  device

Building Gecko and Gaia and using it in an emulator or a real device

If you have a compatible mobile device, you can build and install your own version of Firefox OS and then run it on an Emulator or push it to your device.