Running custom Firefox OS/Gaia builds in WebIDE

Prerequisites

First of all, let's gather the tools we need to run our custom builds in the Simulator.

1. Install Firefox, and make sure you have WebIDE available (Tools > Web Developer > WebIDE.)
2. Install the latest B2G Desktop simulator, or build your own.
3. Install the latest Firefox OS simulator extension, version 7.0pre7.20140113 or later.
4. Build a Gaia profile with the SIMULATOR=1 flag.  For example, you could run the command make SIMULATOR=1 PROFILE_FOLDER=profile-b2g profile-b2g in your Gaia directory to accomplish this (see Hacking Gaia for more details.)

Configuring your simulator

There is some configuration you'll now need to do, so that the simulator can find your B2G Desktop and custom Gaia.

Before Firefox 42

1. Bring up the Add-ons management tab (Tools > Addons, or enter about:addons in the URL bar.)
2. Click on the Extensions tab on the list to list your installed extensions.
3. Locate the new Firefox OS simulator extension in the list. It should be labelled something like Firefox OS 1.3 Simulator 7.0pre.7.20140113.
4. Click on the Preferences button found inside the simulator extension's entry in the list.
   
5. You will want to use a custom executable — the latest B2G Desktop build — for running Firefox OS in WebIDE. Click on the Browse... button next to the Select a custom runtime executable label then browse to your B2G Desktop executable in the file chooser. This will be more obvious in Windows/Linux; on Mac it will be at /Applications/B2G.app/Contents/MacOS/b2g, provided you installed it in the Applications directory. See Building your custom b2g binary if you want to test patches against mozilla-central.
6. You can also run your custom Gaia profile in WebIDE: Click on the Browse... button next to the Select a custom Gaia profile directory label and browse to your custom profile directory (this should be gaia/profile-b2g.)
7. If you need to return to the uncustomized simulator, you must reset a configuration value. Simply deleting and reinstalling the simulator add-on will not work. Open a new tab and enter "about:config" in the address bar. In that page's search field, enter "fxos" or "simulator" and look for something like "extensions.fxos_2_0_simulator@mozilla.org.customRuntime" or "extensions.fxos_2_0_simulator@mozilla.org.gaiaProfile". Right-click and choose "Reset". Now restart the simulator version and you should get the uncustomized version.

Firefox 42 onwards

From Fiefox 42 onwards, you can configure the B2G binary and profile using the "Simulator Options" screen in WebIDE.

Using your configured simulator

Finally, let's get on and use our customized simulator.

1. Open up WebIDE (Tools > Web Developer > WebIDE); you could also press Shift-F8.
2. Open the Runtime menu by clicking the button on the top right.
3. Click on the button for Firefox OS 1.3 (or whatever latest version you have installed). This will be the right option, even if your B2G desktop/Gaia versions are more recent.
4. The simulator will now start; B2G Desktop should load up, running your nightly B2G build and custom Gaia!

Building a custom b2g binary

This is an optional step, useful if you need to test a patch against the mozilla-central codebase.

1. Check out mozilla-central.
2. Apply the patch(s) you want to test.
3. Ensure you have the following content included in your mozconfig:
   ac_add_options --enable-application=b2g
FXOS_SIMULATOR=1
GAIADIR=/home/alex/gaia    # Mandatory to set FXOS_SIMULATOR flag, it will ensure having a working xpi file
MOZTTDIR=/path/to/moztt   # Optional, to get the device fonts

4. Run ./mach build && ./mach package

5. If you specified GAIADIR, you will get a simulator xpi addon in your obdir, within the dist folder.