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 defaultDESKTOP=1
options that comes along withDEBUG=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 yourgaia
directory calledprofile-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 commandmake
. - 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 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) withDEBUG=1 DESKTOP=0 make
. If you want to test using a more realistic production build, just build with the commandmake
. - You can now install the latest mulet into
gaia/firefox
using the commandmake 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 examplefirefox-36.0a1.en-US.mac64.dmg.
The Linux builds are calledtarget.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.
- 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
- 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.