In late February 2014, the Firefox OS Simulator had a feature added that allows it to run a custom B2G binary and/or a Gaia profile of your choosing. This article shows how to configure your toolset to do this, running the Simulator through WebIDE.
First of all, let's gather the tools we need to run our custom builds in the Simulator.
- Install Firefox, and make sure you have WebIDE available (Tools > Web Developer > WebIDE.)
- Install the latest B2G Desktop Nightly, or build your own.
- Install the latest Firefox OS simulator extension, version 7.0pre7.20140113 or later.
- Build a Gaia profile with the
SIMULATOR=1 flag. For example, you could run the command
make SIMULATOR=1 PROFILE_FOLDER=profile-b2g profile-b2gin 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.
- Bring up the Add-ons management tab (Tools > Addons, or enter
about:addonsin the URL bar.)
- Click on the Extensions tab on the list to list your installed extensions.
- 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.
- Click on the Preferences button found inside the simulator extension's entry in the list.
- 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
Applicationsdirectory. See Building your custom b2g binary if you want to test patches against mozilla-central.
- 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.)
- 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 "firstname.lastname@example.orgRuntime" or "email@example.comProfile". Right-click and choose "Reset". Now restart the simulator version and you should get the uncustomized version.
Using your configured simulator
Finally, let's get on and use our customized simulator.
- Open up WebIDE (Tools > Web Developer > WebIDE); you could also press Shift-F8.
- Open the Runtime menu by clicking the button on the top right.
- 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.
- The simulator will now start; B2G Desktop should load up, running your nightly B2G build and custom Gaia!
This is an optional step, useful if you need to test a patch against the mozilla-central codebase.
Note: If you are able to submit Try builds, they will now produce simulator add-ons in the build directory of each B2G desktop platform, so this may be a simpler way to create a simulator that uses custom platform or Gaia changes for some use cases.
- Check out mozilla-central.
- Apply the patch(s) you want to test.
- Ensure you have the following content included in your mozconfig:
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
./mach build && ./mach package
If you specified GAIADIR, you will get a simulator xpi addon in your obdir, within the