This article needs a technical review. How you can help.
This article provides a brief guide to some key things you should know when using the boot to Gecko emulators. This doesn't appear to be a complete user manual; instead, it simply tells you a few useful things that you might not learn on your own.
This guide assumes you've already built one of the emulators; if you haven't, rewind to Building and installing Firefox OS!
About the B2G emulators
There are two B2G emulators. The first, built by configuring for "emulator" when running config.sh, is an ARM device emulator. While this is slower than running directly on an x86 processor, it's more stable and a more accurate representation of what an actual device will work like. Configuring for "emulator-x86" when running config.sh gets you the x86 device emulator instead.
Once you've selected, configured, and built an emulator, the rest works the same way from a user standpoint, so the rest of this guide is common to both.
Starting the emulator
To start the B2G emulator, type the following command:
./run-emulator.sh
This will handle all the emulator startup tasks for you. Now wait patiently while the emulator starts up and Boot to Gecko boots up on it. It can take a couple of minutes, so be patient.
When the emulator doesn't work
Sometimes the emulator fails to start up. Welcome to the bleeding edge of technology! Here are some tips for resolving problems.
Are you trying to work in a VM?
VirtualBox and Parallels have problematic accelerated graphics support which causes a boot failure in the emulator, something about an OpenGL device. The device will start booting, fail, and restart in a loop, or start up, but then display nothing in the screen of the emulator. There is no solution unfortunately (there is a workaround for VirtualBox) - you need to use VMWare Player (Freeware), Workstation or Fusion. For VirtualBox - either do not install Guest Addons, or disable vboxvideo module.
Make sure the adb server is running
This usually happens because the adb server that handles interacting with the emulated device is either not running or has malfunctioned. In this case you can usually see the following error message in the terminal where you launched the emulator:
emulator: control console listening on port 5554, ADB on port 5555 emulator: can't connect to ADB server: Connection refused
Note: If you're using the adb built by the B2G build system (which you probably are), it's located in the $B2G/out/host/<platform>/bin directory. On Mac, this is $B2G/out/host/darwin-x86/bin, for example.
Look to see if adb is even running by doing:
ps aux | grep adb
If it's there, do this to kill it, because it's probably not working correctly.
adb kill-server
If it's not there, do this:
adb start-server
Then try running the emulator again. If it's still not working, time to drop in on #b2g on irc.mozilla.org for help.
Erase configuration settings
Sometimes, out of date configuration settings on your emulated device can cause it to misbehave. You can delete the IndexedDB database fix this, as follows:
- Make sure adb is running, as described in Make sure the adb server is running.
- Start up the emulator.
- in the terminal on the host computer, go into the root code build directory for your emulator, then type:
out/host/<platform>/bin/adb -e shell; on Mac, this would beout/host/darwin-x86/bin/adb -e shell. - Now you're in the adb shell, and can execute shell commands on your emulated device. Let's stop B2G on the device:
stop b2g. - Delete the IndexedDB database:
rm -rf /data/local/indexedDB. - Restart B2G on the emulated device:
start b2g.
Hopefully at this point you will wind up in the Gaia interface and all will be well.
If the emulator starts but the screen is black before or after the "mozilla technology" splash screen
If this happens it could be a driver bug of the machine that is running the emulator. It has been observed on the Linux open source nouveau drivers. The easiest solution is to change the drivers on the machine. In the case of the nouveau driver it could be to install proprietary ("additional" in Ubuntu) drivers instead. In the case of on-board intel graphics chipsets, the default Linux open source driver may cause an emulator error 'eglMakeCurrent failed' which appears to be as it supports an OpenGL version less than the 2.0 needed for GPU emulation. The solution is to deactivate the GPU by editing run-emulator.sh script (this will be slower).
Configuring the emulator
There are several options you can change to adjust the emulator to be more similar to the device you want to emulate. This section provides some basic information on how to do that. You can adjust the emulator's configuration by editing the run-emulator.sh script (or, ideally, a copy of it). Only a few of the most useful parameters are discussed here; you'll want to look at the qemu site for details on the others.
run-emulator.sh for each device you want to simulate; this makes it easy to start up with different configurations.Changing skins
By default, the emulator starts up in HVGA mode; that's half-VGA, or 320x480 pixels. This is specified by the -skin parameter given to the emulator when started up. You can switch to a different display mode by editing the run-emulator.sh script (or, ideally, a copy of it). The provided skins are:
- HVGA (320x480)
- QVGA (240x320)
- WQVGA (240x400)
- WQVGA432 (240x432)
- WSVGA (1024x600)
- WVGA800 (480x800)
- WVGA854 (480x854)
- WXGA720 (1280x720)
- WXGA800 (1280x800)
The skins are located in the B2G/development/tools/emulator/skins directory. It's worth noting that the format for skins is quite simple; if you look at them, they're simply folders filled with PNG files for the various user interface objects and a text file called layout which describes the layout of the interface and screen area. It's fairly simple to create custom skins if needed.
Changing memory size
Another option you may wish or need to configure is the device memory size. The default is 512 MB; however, if the device you're emulating has more or less memory, it is likely important that you adjust this setting to match, to ensure your app will run on the baseline device you want to work on. To do this, change the value of the -memory parameter to the size you need in megabytes. Other than the 512 MB default, 256 MB and 1024 MB are likely ones you'll want to test with.
To change the amount of emulated storage capacity for the device (that is, the storage space for local data, like the flash storage on a mobile phone or the hard drive on a computer), change the value of the -partition-size parameter. The default is 512 MB, but you can specify any size in MB you need in order to simulate the kind of device you need to test for.
Network Connectivity
If for some reason you cannot connect your emulator to the internet you can run the following command from your commandline:
adb shell setprop net.dns1 10.0.2.3
If you run emulator-jb or emulator-kk, the command to set up the DNS server is different.
Please run the following commands:
adb shell ndc resolver setdefaultif eth0 adb shell ndc resolver setifdns eth0 10.0.0.0 10.0.2.3